API Reference

Documentation

Everything you need to verify contractor licenses across the US. One endpoint, structured JSON, real-time data from state licensing boards.

Authentication

All API requests require a Bearer token in the Authorization header.

Include your API key in the Authorization header of every request. You can get your API key from the dashboard after signing up.

Example header

Authorization: Bearer YOUR_API_KEY

Keep your API key secret. Do not expose it in client-side code, public repositories, or browser requests. Always call the API from your backend.

Base URL

All endpoints are relative to the following base URL:

https://api.contractorapi.dev

Verify a License

Look up a specific contractor license by state and license number.

GET/v1/licenses/verify

Query Parameters

Parameter	Type	Required	Description
state	string	Required	Two-letter US state code (e.g. CA, TX, FL)
license_number	string	Required	The contractor's license number

Example Request

curl

curl -X GET "https://api.contractorapi.dev/v1/licenses/verify?state=CA&license_number=1077911" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK

{
  "verified": true,
  "license_number": "1077911",
  "state": "CA",
  "full_name": "MARTINEZ ELECTRIC INC",
  "profession": "electrician",
  "state_classification": "C-10 Electrical",
  "status": "active",
  "issue_date": "2019-03-15",
  "expiration_date": "2027-03-31",
  "bond_status": "active",
  "workers_comp": "exempt",
  "last_verified": "2026-03-28T14:22:00Z",
  "source": "California CSLB"
}

Response Fields

Field	Type	Description
verified	boolean	Whether the license was found and is verifiable
license_number	string	The license number as recorded by the state
state	string	Two-letter state code
full_name	string	Licensed entity or individual name
profession	string	Normalized profession type (electrician, plumber, hvac, roofing, general_contractor)
state_classification	string	The state's own license classification or trade code
status	string	License status: active, expired, suspended, revoked, or inactive
issue_date	string	Date the license was originally issued (ISO 8601)
expiration_date	string	Date the license expires (ISO 8601)
bond_status	string	Surety bond status: active, expired, not_required, or unknown
workers_comp	string	Workers compensation status: covered, exempt, expired, or unknown
last_verified	string	Timestamp of when this data was last pulled from the source (ISO 8601)
source	string	Name of the state licensing board or data source

Search by Name

Search for contractor licenses by name within a state. Useful when you have a name but not a license number.

GET/v1/licenses/search

Query Parameters

Parameter	Type	Required	Description
state	string	Required	Two-letter US state code
name	string	Required	Business or individual name to search for
profession	string	Optional	Filter by profession (electrician, plumber, hvac, roofing, general_contractor)

Example Request

curl

curl -X GET "https://api.contractorapi.dev/v1/licenses/search?state=CA&name=Martinez" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK

{
  "state": "CA",
  "query": "Martinez",
  "total_results": 2,
  "results": [
    {
      "license_number": "1077911",
      "full_name": "MARTINEZ ELECTRIC INC",
      "profession": "electrician",
      "state_classification": "C-10 Electrical",
      "status": "active",
      "expiration_date": "2027-03-31"
    },
    {
      "license_number": "982104",
      "full_name": "MARTINEZ & SONS PLUMBING",
      "profession": "plumber",
      "state_classification": "C-36 Plumbing",
      "status": "active",
      "expiration_date": "2026-11-30"
    }
  ]
}

List Supported States

Returns all states currently supported by the API.

GET/v1/states

Example Request

curl

curl -X GET "https://api.contractorapi.dev/v1/states" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK

{
  "total": 5,
  "states": [
    { "code": "AZ", "name": "Arizona", "source": "Arizona ROC", "professions": ["general_contractor", "electrician", "plumber", "hvac", "roofing"] },
    { "code": "CA", "name": "California", "source": "California CSLB", "professions": ["general_contractor", "electrician", "plumber", "hvac", "roofing"] },
    { "code": "FL", "name": "Florida", "source": "Florida DBPR", "professions": ["general_contractor", "electrician", "plumber", "hvac", "roofing"] },
    { "code": "MA", "name": "Massachusetts", "source": "Massachusetts DPL", "professions": ["electrician", "plumber", "hvac"] },
    { "code": "TX", "name": "Texas", "source": "Texas TDLR", "professions": ["electrician", "plumber", "hvac", "roofing"] }
  ]
}

Status Codes

Standard HTTP status codes returned by the API.

Code	Status	Description
200	OK	Request succeeded. License data returned in the response body.
400	Bad Request	Missing or invalid query parameters. Check that `state` and `license_number` are provided.
401	Unauthorized	Missing or invalid API key. Ensure the `Authorization` header is set correctly.
404	Not Found	No license found matching the provided state and license number combination.
429	Too Many Requests	Rate limit exceeded. Check the `Retry-After` header for when you can retry.

Error Response Format

Example error (400)

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: license_number",
    "status": 400
  }
}

Rate Limits

Rate limits are applied per API key based on your plan.

Plan	Rate Limit	Price
Free	25 requests / day	$0
Starter	1,000 requests / day	$0.25 / verification
Growth	5,000 requests / day	$0.18 / verification
Scale	Unlimited	$0.12 / verification

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

SDKs & Tools

Libraries and integrations to get started faster.

MCP Server

Connect AI agents and LLMs directly to the license verification API using the Model Context Protocol. Works with Claude, ChatGPT, and any MCP-compatible client.

npx @contractorapi/mcp-server

REST API

Standard REST API with JSON responses. Works with any HTTP client -- curl, fetch, axios, httpx, or your language of choice. No SDK required.

Content-Type: application/json

Python SDK

Coming soon

Official Python client with type hints, async support, and automatic retries.

pip install contractorapi

Node.js SDK

Coming soon

Official TypeScript/JavaScript client for Node.js with full type definitions.

npm install @contractorapi/sdk

Roadmap

License verification is just the start. Here's what's coming next.

Live now

License Verification

Real-time license status, bond info, workers' comp, and state classifications across all 50 states.

Q3 2026

Business Entity Checks

Secretary of State data. Verify registration status, incorporation type, and registered agent info.

Q4 2026

Litigation History

Court records, liens, judgments, and disciplinary actions. Federal and state courts.

2027

Permits & Zoning

Building permit history, zoning data, and code violations across US jurisdictions.

The long-term vision: one API call that tells you everything about a contractor. License, entity, litigation, permits. We're building it layer by layer.

Ready to get started?

Get early access