PermitIntel Data API

GET /api/v1/permits

Permits by address, by contractor, by jurisdiction (browse, newest first), or as a change feed by updated_since. Filter by trade, work_type, status, county, min_value, and date range. Add include=contractor_contact to nest the licensed contractor's business name, phone, email, and verified website.

Every parameter is listed with the modes it applies in, and that column is enforced: a parameter sent outside its modes comes back 400 filter_unsupported_in_mode with an example_url that works, and a parameter name we do not recognize comes back 400 unknown_param. Nothing is accepted and quietly ignored, so a typo in your URL can never look like a gap in our data.

jurisdiction is case-insensitive. Florida jurisdiction codes are upper-case and prefixed (FL-ORANGE-ORLANDO); jurisdictions ingested outside Florida are bare and lower-case (san_francisco). Either spelling resolves, and the query.jurisdiction in the response tells you which code answered.

The code format is STATE-COUNTY-PLACE, upper-case, with underscores inside a multi-word name and hyphens only between the three segments: CA-CONTRA_COSTA-WALNUT_CREEK, FL-MIAMI_DADE-MIAMI_BEACH. A county-level code is two segments (NC-ALAMANCE). There is no CITY_OF_ prefix, no ZIP in the place segment, and a hyphen inside a name (WALNUT-CREEK) is not a code we hold. Do not guess: GET /api/v1/jurisdictions lists every code with its permit counts. Send your key for the codes themselves; without one you get the counts. It costs no records either way, and takes state, county and q to narrow.

If a well-formed code returns nothing, the response carries a did_you_mean block naming the codes we dohold in that county, most records first — and if the county segment itself is misspelled, it names the closest county code we publish. An empty page never has to be read as “no permits there”.

curl "https://permitintel.ai/api/v1/permits?contractor=CCC1335488" \
  -H "Authorization: Bearer pmit_your_key"

Parameters

Browse a jurisdiction

A jurisdictionon its own returns that jurisdiction's permits, most recently issued first. It is the quickest way to see what we hold for a place before you have an address or a contractor name.

trade works here, bounded to a 180-day window. Ordering a whole jurisdiction by date and filtering it on free-text work descriptions cannot be bounded when nothing in that jurisdiction matches the trade — the scan runs to the end looking for rows that are not there — so the window is what keeps it inside a budget we are willing to promise. Every trade-filtered browse reports the window it searched as a top-level trade_window object on the response (next to trade_source, not under meta), including exhausted: true means you are holding every match in the window, false means the page hit its limit and there are more. Pass from and to inside a 180-day span to move the window anywhere in history. The change feed (updated_since) applies trade with no window limit, but matches it differently — see the next paragraph.

Where trade comes from. In browse, address and contractor mode, for roofing, hvac, electrical, pool, solar, windows_doors and fence, a trade is assigned by our permit classifier, which reads the permit's type and class fields and its description. For general, plumbing and demolition it is still a keyword match over permit_type, work_class and type_of_work — general has no classifier tag at all, and for the other two we measured that the keyword match is the more complete answer today. Every trade-filtered response tells you which matcher ran, in trade_source, so you never have to infer it.

The change feed matches every trade on keywords. It is the one mode that does not use the classifier, and trade_source.matcher on a feed response always reads keywords. The reason is the shape of the mode: the feed orders every changed permit by updated_at across the whole corpus, so it evaluates the trade against the permit description after the rows are read, inside a scan budget — which is also why a feed page can be short and report meta.scan_complete: false. The practical consequence is that the same ?trade=roofing can return a different set in the feed than in browse, so compare feed pages to feed pages. trade_confidence and trade_match are refused in feed mode with filter_unsupported_in_mode rather than accepted and ignored.

Two parameters control it. trade_confidence=highkeeps only trades named in the permit's type/class fields and drops those found only in the description: narrower and more precise, but zero rows in jurisdictions whose permit types are generic and whose only trade signal is the description — Los Angeles is one of them. The default, any, includes both. trade_match=keywords pins a request to the keyword matcher for every trade, which is the exact behaviour of this endpoint before 30 September 2026.

county is not available in browse mode: it is a code prefix covering many jurisdictions, and a prefix range cannot be walked in date order — the planner has to sort the whole county before it can honour a limit. Name a jurisdiction inside the county, or poll the feed, where county works.

curl "https://permitintel.ai/api/v1/permits?jurisdiction=FL-ORANGE-ORLANDO&limit=25" \
  -H "Authorization: Bearer pmit_your_key"

# lower-case, nationally-ingested jurisdiction codes work the same way
curl "https://permitintel.ai/api/v1/permits?jurisdiction=san_francisco&limit=25" \
  -H "Authorization: Bearer pmit_your_key"

# trade in browse: the newest 180 days of roofing permits in one jurisdiction
curl "https://permitintel.ai/api/v1/permits?jurisdiction=CA-CONTRA_COSTA-DANVILLE&trade=roofing&limit=100" \
  -H "Authorization: Bearer pmit_your_key"

# ...and anywhere in history, by moving the window
curl "https://permitintel.ai/api/v1/permits?jurisdiction=CA-CONTRA_COSTA-DANVILLE&trade=roofing&from=2024-01-01&to=2024-06-28" \
  -H "Authorization: Bearer pmit_your_key"

Errors

Poll for new permits weekly

from and tofilter on the permit's issue date, so a permit we ingest today carrying a 2019 issue date never shows up in a date-window poll — and records arriving from public-records responses, rescrapes, and status refreshes are most of what lands. updated_since filters on when the recordchanged instead, which is what "everything new since my last run" actually means. Rows come back oldest-change-first so the walk is resumable; store meta.next_cursor and pass it back as cursor until it comes back null.

# 1. first run: everything changed since your last sync
curl "https://permitintel.ai/api/v1/permits?updated_since=2026-09-01T00:00:00Z\
&state=FL&trade=roofing&limit=200&include=contractor_contact" \
  -H "Authorization: Bearer pmit_your_key"

# 2. walk the pages
curl "https://permitintel.ai/api/v1/permits?updated_since=2026-09-01T00:00:00Z\
&state=FL&trade=roofing&limit=200&cursor=MjAyNi0wOS0wMVQwMDowMDowMFp8MTIz" \
  -H "Authorization: Bearer pmit_your_key"

# 3. next run: only permits FIRST INGESTED since then, not every record we touched
curl "https://permitintel.ai/api/v1/permits?updated_since=2026-09-08T00:00:00Z\
&new_only=true&state=FL&trade=roofing&limit=200" \
  -H "Authorization: Bearer pmit_your_key"

In Zapier, n8n, or Clay the same three steps are: a schedule trigger; an HTTP GET with updated_since set to the value you stored last run; a loop that re-issues the GET with cursor while meta.has_moreis true; then store the run's start time for the next trigger. Two things to build against rather than discover: a page can return fewer rows than limit and still not be the end — the feed ends when next_cursor is null, never on a short page — and without new_only this is a change feed, not a new-permit feed: it includes enrichment and status updates to permits you have already seen, which is what you want for keeping a mirror in sync and not what you want for lead alerts.

A trade filter on the feed can hand back an empty page that is not the end.A trade is matched against the permit's own work wording after the rows are read, not by an index, so each page scans a bounded window and returns whatever in it matched. Where a trade is thin on the ground, early pages come back short or empty. Those pages carry meta.scan_complete: false and a next_cursor pointing at where the scan stopped rather than at the last row served, so the walk still moves forward. Page until next_cursor is null; never stop on a zero-row page, and never read one as “no permits of this trade here”.

Jurisdiction ids are not ZIP codes. They look like CA-CONTRA_COSTA-ANTIOCH (state, county, place), or, for our national sources, a bare lowercase slug such as san_francisco. To see every id we hold inside a county, call /v1/jurisdictions?county=CA-CONTRA_COSTA; ?state= and ?q= reach the bare slugs, which carry no county prefix. A feed request under a code we hold nothing for answers 200 with a did_you_mean block and says the page is empty because the code is not one of ours, rather than leaving you to read an empty page as an empty market.

state is available on the feed only. On an address or contractor lookup, use jurisdiction (exact, e.g. FL-ORANGE-ORLANDO) or county (a prefix, e.g. FL-MIAMI_DADE), which are exact rather than approximate.

County change feeds are supported. county combined with updated_since is answered by scanning each jurisdiction inside the county and merging the results in cursor order, so one poll keeps a whole county in sync and the cursor resumes across it exactly as it does for a single jurisdiction. Every county we hold fits; a county naming more than 40 jurisdictions would come back feed_filter_too_broad rather than a quietly short page.

A state-wide change feed is the one shape we cannot serve: state is not indexed together with updated_at, so state plus updated_since is refused with feed_filter_too_slow rather than left to hang. For a state, either poll its counties, or poll the feed with no jurisdiction filter at all — that shape is fast — and filter on your side.

GET /api/v1/jurisdictions

The jurisdiction codes you can pass to jurisdiction and county, so you never have to guess one. Send your key for the codes; a keyless caller gets the counts and the filters but not the list. Free of records either way. Narrow with state (two letters), county (a code prefix such as FL-MIAMI_DADE) or q (a substring of the code), and page with limit and offset. Each row carries the code, its state and county, total permits on file, the trailing-12-month count, how many of those permits resolved to a contractor license, and when we last ingested it. Counts are a floor on what we hold, not a completeness claim, and jurisdictions whose records sit under a raw dataset identifier rather than a place code are not listed.

curl -H "x-api-key: pmit_your_key" \
  "https://permitintel.ai/api/v1/jurisdictions?county=FL-MIAMI_DADE"

A browse that returns nothing under a well-formed code answers 200 with a did_you_mean block listing the codes we do hold in the same county, most records first — so an empty page never has to be read as “no permits there”. It is not a spelling correction, and the list is not exhaustive.

curl "https://permitintel.ai/api/v1/permits?jurisdiction=FL-MIAMI_DADE-MIAMI" \
  -H "x-api-key: pmit_your_key"

GET /api/v1/permits/{id}

One permit, by the id on every row the search returns — the same object, with the contractor’s contact already nested rather than behind include. The key is the internal id, not the permit number: permit offices number independently, so one permit number names different buildings in different jurisdictions and cannot identify a single record. Send a permit number and you get 400 bad_permit_id saying so, never a 404. A permit we hold but do not serve answers 404 — the same records the search would never return.

curl "https://permitintel.ai/api/v1/permits/236705358" \
  -H "x-api-key: pmit_your_key"

GET /api/v1/contractors

A contractor by license, or search by name or specialty. Every result carries a permit-activity rollup: permit count, declared value, 12-month trend, top trades, top jurisdictions, and last-active date, plus verified workers-comp and EPA lead-safe signals and canonical contact.

curl "https://permitintel.ai/api/v1/contractors?specialty=roofing&county=Lee" \
  -H "x-api-key: pmit_your_key"

Rank a market by activity. Add sort (permits_12mo, permits, value_12mo, value, last_active) and floor it with min_permits or min_permits_12mo. This is the supplier and sales-intelligence workflow: the busiest roofers in a county, ranked, ready to call.

curl "https://permitintel.ai/api/v1/contractors?specialty=roofing&county=Lee&sort=permits_12mo&min_permits_12mo=5" \
  -H "x-api-key: pmit_your_key"

GET /api/v1/contractors/{license}

One contractor profile by DBPR license number — exactly what ?license= returns, plus links.permits (their full permit history URL) and recent_permits, their ten most recent permits in the same row shape the permit search uses. The license number is the identity: there is no contractor UUID, because every join in the product is keyed on the license. recent_permits is a sample, never a history — activity.permit_count is the count on record and links.permits is the paged history.

curl "https://permitintel.ai/api/v1/contractors/CGC1524985" \
  -H "x-api-key: pmit_your_key"

GET /api/v1/verify/license

The trust primitive. An authoritative DBPR license check by license (or name plus county), refreshed daily. Returns status, type, effective and expiration dates, the qualifier, and a computed is_active and expires_in_days. Available on every plan, including the free trial.

curl "https://permitintel.ai/api/v1/verify/license?license=CCC1331234" \
  -H "Authorization: Bearer pmit_your_key"

GET /api/v1/verify/insurance

Workers-comp coverage status and lapse intelligence for a licensed business, from Florida DWC and Texas DWC proof-of-coverage and California CSLB records. Returns wc_status (active, expired, cancelled, or not_found), carrier, and policy dates, plus a coverage array carrying general liability and surety bond where the state publishes them (WA L&I, OR CCB). A not_found result means we hold no matched workers-comp record for that license, not that the business is uninsured. Pass &state= when a bare license number exists in more than one state. B2B verification of a business, not consumer underwriting. Starter and up.

curl "https://permitintel.ai/api/v1/verify/insurance?license=CCC1331234" \
  -H "x-api-key: pmit_your_key"

GET /api/v1/verify/certifications

Compliance badges in one call: EPA RRP lead-safe certification and Florida minority or disadvantaged business designation, matched to the license. Starter and up.

curl "https://permitintel.ai/api/v1/verify/certifications?license=CCC1331234" \
  -H "x-api-key: pmit_your_key"

POST /api/v1/monitors

Turn a one-time lookup into an always-on subscription. Watch a license for a license lapse, an insurance lapse, a new permit, or a certification expiry, and get a webhook or poll for events. Built for insurers, lenders, GC networks, and marketplaces continuously verifying a roster. Growth and up.

To subscribe, POST to /api/v1/monitors with Content-Type: application/json. The body carries license, an events array drawn from license_lapse, insurance_lapse, new_permit and certification_expiry, and an optional webhook_url. Leave the webhook off and poll the events endpoint instead.

# list yours
curl "https://permitintel.ai/api/v1/monitors" -H "x-api-key: pmit_your_key"

# poll events (no webhook needed)
curl "https://permitintel.ai/api/v1/monitors/<id>/events?since=2026-06-01" -H "x-api-key: pmit_your_key"

# stop watching
curl -X DELETE "https://permitintel.ai/api/v1/monitors/<id>" -H "x-api-key: pmit_your_key"

Webhook deliveries are signed X-PermitIntel-Signature: sha256=HMAC(secret, body) with a per-monitor secret returned once at creation.

GET /api/v1/supply/accounts

Roll every Florida contractor up into a supplier sales account: demand by trade, momentum (90 days versus the prior 90), an activity grade A to D, a territory rank, serviceability (canonical email, phone, and workers-comp on record), and contact depth: every phone and email on record for the business, ranked by how often permits, county registries, and the state licensing board carried it, each with its sources and last-seen date, plus the website and filed address. Government mailboxes, permit expediters, placeholders, and numbers shared across unrelated businesses are filtered out before you see the list. Filter by county, trade, minimum 12-month permits, momentum band, and grade; sort by value, permit count, momentum, or roofing activity. Add format=csv to hand a rep the whole territory. Growth and up.

curl "https://permitintel.ai/api/v1/supply/accounts?county=Broward&trade=roofing&min_permits_12mo=5&momentum=growing&grade=A&sort=value_12mo" \
  -H "x-api-key: pmit_your_key"

# whole territory as a spreadsheet
curl "https://permitintel.ai/api/v1/supply/accounts?county=Broward&trade=roofing&format=csv" \
  -H "x-api-key: pmit_your_key"

Demand figures are permit-activity proxies, a floor and not a complete record, and the activity grade is a sales-prioritization signal, not a credit score.

Supplier workspace (book, reps, territories)

Turn the scored-account feed into a working book of business: save accounts with a pipeline status, assign them to reps, store reusable territory filters, and put any account on a watch. A watched account reuses the monitoring engine, so a new permit, a license lapse, or an insurance lapse fires the same poll or signed webhook. Growth and up.

All three write endpoints take Content-Type: application/json. A rep needs name and email. A book entry needs license and status, and optionally rep_id, watch, and webhook_url to put the account on the monitoring engine. A territory needs name plus whichever account filters you want stored: county, trade, min_permits_12mo, momentum, grade, and rep_id. PATCH the book with a license and the new status to move an account down the pipeline.

# list the book (each row enriched with live demand, momentum, grade)
curl "https://permitintel.ai/api/v1/supply/book?status=contacted" -H "x-api-key: pmit_your_key"

Pipeline statuses: prospect, contacted, active, won, lost. Resolve a saved territory by passing its fields to /api/v1/supply/accounts for the live ranked list.

GET /api/v1/roof/{address}

Roof state for one property: roof_age_years (derived from the most recent roof permit on record), roof_last_permit_date, and roof_material with source and confidence. Add ?zip= to disambiguate. Every response carries a per-jurisdiction coverage_grade (A, B, or C) so a miss reads as not covered, never as no roof work. On every plan, including the trial.

curl "https://permitintel.ai/api/v1/roof/2082%20HYDE%20PARK%20ST?zip=34239" \
  -H "Authorization: Bearer pmit_your_key"

GET /api/v1/roof/{address}/evidence

The citation layer behind a roof answer: the underlying roof permit record(s) with permit number, jurisdiction, issue date, contractor and license, declared value, and status. Proof an underwriter or inspector can file. On every plan.

curl "https://permitintel.ai/api/v1/roof/2082%20HYDE%20PARK%20ST/evidence?zip=34239" \
  -H "x-api-key: pmit_your_key"

POST /api/v1/roof/batch

Score a book of business: up to 1,000 addresses per request, returned in input order with match status, roof age, material, and jurisdiction. Loop requests for bigger books. Growth and up.

POST with Content-Type: application/json and a body containing an items array. Each entry carries an address and an optional zip to disambiguate.

GET /api/v1/roof/coverage

The coverage table behind the grades. Without a key you get the totals and the A/B/C histogram, filterable by state, county, or grade. Send your key for the per-jurisdiction rows: property counts, roof-age fill rate, material fill rate, data freshness, and the grade. The detail costs no records on any plan.

curl -H "Authorization: Bearer $PERMITINTEL_API_KEY" \
  "https://permitintel.ai/api/v1/roof/coverage?state=FL&grade=A"