API & Data | Builders Monitor

Quickstart

Authenticate, then call

Every request carries your key in the X-Api-Key header. Mint keys under Account → API Keys— they’re shown once at creation, so store them securely.

1
Create a key. Generate one in your account. The token is displayed a single time — copy it before you leave the page.
2
Send it on every request. Add X-Api-Key: prefix.secret as a header. Unauthenticated calls return 401.
3
Stay in budget. Search/browse is free; a detail fetch costs one lookup, deduplicated once per record per month per account.

curl -H "X-Api-Key: $BM_API_KEY" \
  "https://api.buildersmonitor.com/v1/permits?state=CA&permit_type=Building&limit=20"

Capabilities

What the API does

Permit search

Filter by state, city, type, status, issue date, and valuation. Browse and search are free — no lookup quota consumed.

Full permit detail

Inspections, fees, and contacts on one record. Charges a single lookup, deduplicated once per record per month per account.

Contractor records

Search and retrieve contractor entities linked across jurisdictions and permits.

Bulk exports

POST your filters and get an expiring signed link to a zstd-compressed JSONL (.jsonl.zst) slice, capped by your plan's row limit.

Entitlement scoping

Every key is scoped to your plan's coverage and rate limits, enforced server-side.

Same-origin tester

Try any endpoint live from the in-browser reference — paste a key and send.

Endpoints

Core requests, in your language

The same call in cURL, Python, and JavaScript. Browse the full surface — every parameter, schema, and response — in the interactive reference.

GET/v1/permits

Keyset-paginated permit search. Free — no lookup quota consumed.

curl -H "X-Api-Key: $BM_API_KEY" \
  "https://api.buildersmonitor.com/v1/permits?state=CA&permit_type=Building&limit=20"

GET/v1/permits/{permit_id}

Full detail — inspections, fees, contacts. Charges one lookup (deduped per record/month).

curl -H "X-Api-Key: $BM_API_KEY" \
  "https://api.buildersmonitor.com/v1/permits/3f5a9b00-1c2d-4e5f-8a9b-0c1d2e3f4a5b"

POST/v1/permits/export

Request a bulk export via filter query params. Paid plans only — rows capped by your plan’s export_rows_per_month.

curl -X POST -H "X-Api-Key: $BM_API_KEY" \
  "https://api.buildersmonitor.com/v1/permits/export?state=CA&permit_type=Building&issued_from=2024-01-01"

Download the result from the signed link, then decompress.

# $DOWNLOAD_URL is the relative download_url from the export response —
# it must be prefixed with the API origin before requesting it.
curl -o permits.jsonl.zst "https://api.buildersmonitor.com$DOWNLOAD_URL"
zstd -d permits.jsonl.zst   # decompress to permits.jsonl

Bulk exports

Whole slices, one format

Need more than a page at a time? Request an export and download your filtered slice as zstd-compressed JSONL.

.jsonl.zst

JSONL + zstd

One JSON record per line, zstd-compressed. Streams straight into DuckDB, Spark, or jq — decompress with `zstd -d file.jsonl.zst`.

Export lifecycle

Request → generate → download

Every export request returns 202immediately with status “pending” — generation runs async server-side. The response carries a download_url that becomes valid once generation completes: an expiring signed link.