# Licensed Contractors API reference

Use this as compact context for the live bluedoor Licensed Contractors API.

Primary URLs:

- API base URL: https://api.bluedoor.sh/licensed-contractors/v1
- OpenAPI JSON: https://bluedoor.sh/apis/licensed-contractors/docs/openapi.json
- Upstream OpenAPI JSON: https://api.bluedoor.sh/licensed-contractors/v1/openapi.json
- Docs: https://bluedoor.sh/apis/licensed-contractors/docs
- Landing page: https://bluedoor.sh/apis/licensed-contractors

Authentication:

- API keys are optional. Anonymous requests work at lower rate limits.
- Pass a key as "x-api-key: <key>" or "Authorization: Bearer <key>" when you have one.

Taxonomy:

- Contractor firm: aggregate identity with firm_id, canonical name, first/last seen, observed work-event count, observed project value, source count, and links.
- Local identity: source-specific contractor record with local_identity_id, portal_key, business_display_name, license_number, qualifier, contacts, source_record_id, source_url, and optional source_fields.
- Work event: permit/job observation with work_event_pk, firm_id, local_identity_id, work_event_id, work_type, work_category, project_value, work_date, status, location, and provenance.
- DBPR license and complaint: state license context joined by normalized license number.
- Coverage county: county-level completeness, tier, caveats, counts, date span, source keys, and next decision.
- Source and artifact: portal/source registry plus fetched artifact metadata, hashes, row counts, and blocker/proof notes.
- Facet: count-bearing values for county, portal_key, work_category, license_status, and license_type.

Conventions:

- Every success is an envelope: {"data": ..., "meta": {...}}.
- meta always has api_version, request_id, generated_at, product; lists add limit, offset, and next_cursor.
- Lists paginate with an opaque cursor echoed back as meta.next_cursor. limit defaults to 50 and is capped at 500.
- Errors are {"error": {"code", "message", "details"?}, "meta": {...}} except framework-level 405s, which return {"detail": "Method Not Allowed"}.
- Observed project value is source-attributed permit/job value, not verified revenue.
- County coverage can be partial or city-scoped; inspect /v1/coverage/counties and /v1/sources before treating counts as complete.

Important routes:

- GET /health
- GET /v1
- GET /v1/openapi.json
- GET /v1/stats
- GET /v1/coverage/counties, GET /v1/coverage/counties/{county}
- GET /v1/sources, GET /v1/sources/{portal_key}
- GET /v1/source-artifacts, GET /v1/source-artifacts/{artifact_id}
- GET|POST /v1/contractors/search
- GET /v1/contractors/{firm_id}
- GET /v1/contractors/{firm_id}/local-identities
- GET /v1/contractors/{firm_id}/work-events
- GET /v1/local-identities/{local_identity_id}
- GET /v1/work-events/search
- GET /v1/work-events/{work_event_pk}
- GET /v1/licenses/search
- GET /v1/licenses/{license_number}
- GET /v1/licenses/{license_number}/complaints
- GET /v1/facets

Examples:

```bash
curl "https://api.bluedoor.sh/licensed-contractors/v1/contractors/search?q=tadlock%20roofing&limit=2"

curl "https://api.bluedoor.sh/licensed-contractors/v1/contractors/firm_e586aa72e7c720eb3ad6?include=licenses"

curl "https://api.bluedoor.sh/licensed-contractors/v1/work-events/search?county=Leon&limit=2"

curl "https://api.bluedoor.sh/licensed-contractors/v1/licenses/CCC1328417"

curl "https://api.bluedoor.sh/licensed-contractors/v1/coverage/counties/Leon"

curl "https://api.bluedoor.sh/licensed-contractors/v1/facets?field=county&limit=5"
```