CSV count and cost preview
Use GET /v1/permits/export?preview=true with the same filters as the download. The preview reports record_count, credit_cost and truncated. Pass expected_rows and expected_credit_cost on the download; a changed quote returns a conflict and requires a fresh preview. Previewing returns metadata only and is free.
Permits
Search and retrieve building permits
GET/v1/jurisdictions
List Covered Jurisdictions
Covered jurisdictions with measured currency and source-capture labels where available.
`data_through` is the newest held permit date where measured, not a poll time.
Dates and capture estimates may be unknown; a current date does not establish
complete capture. `freshness_label` and `completeness_label` use the shared
definitions also used by the export picker and delivered manifest.
`last_refreshed` is the UTC date we last finished reading the source, whether or not it
had anything new: a refresh date, never a currency claim (that is `data_through`).
`previous_names` lists the names the same jurisdiction `id` was published under before,
oldest first, each with the date it stopped being used. The id never changes on a rename.
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/jurisdictions"
GET/v1/permits/address/{address}
Get Permits By Address
Search a page of held permit records using a partial address match. Results depend on source coverage, address matching, pagination and plan history limits. A match can include multiple properties; an empty result does not prove that no permit or work exists.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
addressrequired | string | |
page | integer | default: 1 |
per_page | integer | default: 25 |
record_kind | string | 'permit' (default), a specific record_kind, or 'all'. default: "permit" |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitSearchResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | PermitSummary[] | |
hints | Hint[] | |
coverage_confidence | CoverageConfidence | |
tier_window_days | integer | |
tier_window_from | string | |
tier_window_clamped | boolean | |
tier_window_upgrade_url | string | |
locked_fields | string[] | |
locked_upgrade_url | string | |
coverage | JurisdictionCoverage[] | |
total_capped | boolean | |
total_unknown | boolean |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/permits/address/{address}"GET/v1/permits/events
List Permit Events
What CHANGED, instead of re-reading everything: permit transitions
(new_permit, status_change, issued, completed, expired) built from the daily
ingest diff, filterable by city, state, category and jurisdiction.
**This is the endpoint to poll on a schedule, and `cursor` is how to poll it.**
Save the `next_cursor` from each response and pass it back as `cursor` on the
next call; you then receive only what you have not already seen, in the order it
was detected, with no duplicates and no gap. Page until a response comes back
shorter than `per_page`, save that last `next_cursor`, and resume there tomorrow.
**WHERE YOU START MATTERS, AND THE FIRST CALL DOES NOT START AT THE BEGINNING.**
A call with NO cursor returns the NEWEST events and its `next_cursor` is the
frontier -- a watermark at "now". Pass it straight back and you correctly get 0
results, because you have just declared yourself caught up. That is exactly what
a poller wants: from here on you receive everything new. It is NOT a backfill,
and it will not walk history for you -- there are 75,544 events behind that
watermark for the Tampa filter below alone.
To start somewhere else, build the cursor yourself: it is
`<ISO-8601 timestamp>|<event id>`, and `|0` is a valid id floor.
# start polling from now (typical):
GET /v1/permits/events?city=Tampa&state=FL&category=roofing
&event_type=new_permit -> save next_cursor
# ...then, from the next call onward:
GET ...&cursor=2026-09-08T04%3A09%3A16.381111%2B00%3A00%7C51823904
# start from a chosen point instead (backfill the last 30 days, then keep polling):
GET ...&cursor=2026-08-11T00%3A00%3A00%2B00%3A00%7C0
One call answers what a paged re-pull of /v1/permits/search costs hundreds of.
Measured 2026-09-09, that Tampa query returns **38 records in a single call**;
the same question asked by re-pulling search pages 1-100 twelve times a day
costs ~9,600 requests and runs into the daily cap.
`detected_after` still works and is fine for an ad-hoc look at a window, but it
is the wrong tool for a poller: it is INCLUSIVE, and one ingest batch stamps
thousands of events with a single identical `detected_at` (measured 2026-09-10:
3,688 timestamps carry over 1,000 events each, the largest 1,370,561). A poller
that stores the newest `detected_at` and passes it back therefore re-receives
that whole batch every time. `cursor` breaks the tie on the event id and does not.
Supplying a `cursor` returns events oldest-unseen first, which is what lets a
batch be paged safely; without one you get the newest first, for browsing.
`cursor` and `page` are alternatives -- passing both is a 400 rather than a
silently skipped page.
Ingest runs once a day, so a daily poll is enough; `detected_at` is when WE saw
the change, not when the city recorded it. For push instead of poll, register a
webhook (developer tier and above) and skip the polling entirely.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
event_type | string | Filter by event type: new_permit, status_change, issued, completed, expired (the permit's expiration date has passed without it being finished; emitted when that date arrives) |
category | string | Permit category (e.g. solar, battery) |
city | string | City name |
state | string | 2-letter state code |
jurisdiction | string | Jurisdiction name (partial) |
permit_id | string | Events for a single permit id |
detected_after | string | Only events detected on/after this UTC timestamp (ISO 8601). Inclusive, so a batch sharing one timestamp is re-delivered; prefer `cursor` for polling. |
cursor | string | Opaque cursor from the previous response's `next_cursor`. Resumes exactly where you stopped, with no duplicates and no gap. Omit on the first call. |
page | integer | default: 1 |
per_page | integer | default: 50 |
limit | integer | Alias of `per_page`. Clamped to 100, not rejected. |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitEventsResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | PermitEventOut[] | |
total_capped | boolean | |
total_unknown | boolean | |
hints | Hint[] | |
next_cursor | string | Pass back as `cursor` to receive only events you have not seen yet, with no duplicates and no gap. Null when this page cannot define a resume point (i.e. a `page` beyond the first, where the newest row on the page is not the newest overall). |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/permits/events"
GET/v1/permits/export
Export Permits
Export permits matching the same API filters as CSV. Plan row limits or available
credits cap the download. Use preview=true for the exact bounded record count and credit
cost, then expected_rows and expected_credit_cost to confirm them before downloading.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
preview | boolean | Count this bounded export without returning records. Preview pricing is reported by /v1/credits/balance; credit_cost quotes the subsequent download. default: false |
expected_preview_credit_cost | integer | Refuse sizing if its own credit cost changed since balance was read. |
expected_rows | integer | Refuse download if the count changed since preview. |
expected_credit_cost | integer | Refuse download if the credit cost changed since preview. |
zip_code | string | |
city | string | |
state | string | |
category | string | |
status | PermitStatus | |
property_type | PropertyType | |
tag | string | |
record_kind | string | default: "permit" |
filed_after | string | |
filed_before | string | |
issued_after | string | |
issued_before | string | |
date_after | string | On or after this date, matched against whichever date a record has (issued, else filed). |
date_before | string | On or before this date, matched against whichever date a record has (issued, else filed). |
parcel | string | Parcel number / APN / folio (formatting ignored). |
min_value | number | |
max_value | number | |
min_solar_kw | number | |
max_solar_kw | number | |
min_sqft | number | |
has_enrichment | boolean | |
scope | string | |
q | string | |
contractor_name | string | |
owner_filed | boolean | true selects records with no linked contractor and a recorded owner name, using source contractor coverage checks; false selects records with a linked contractor. This filter does not verify who filed, homeowner status or purchase intent. |
jurisdiction | string | A jurisdiction's id (from /v1/jurisdictions) or its name, partial and case-insensitive -- the same matching as /v1/permits/search. Lets a full load be partitioned along the coverage list. |
limit | integer | Rows to return, up to your plan's export maximum (a larger value is refused with 403, never silently lowered). If more rows match than `limit`, the response header X-Permitstack-Truncated is `true`: narrow the filter or split the date range and export again. default: 1000 |
keyword | string | Alias of `q`. |
date_from | string | Alias of `date_after`. |
date_to | string | Alias of `date_before`. |
start_date | string | Alias of `date_after`. |
end_date | string | Alias of `date_before`. |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/permits/export"
GET/v1/permits/search
Search Permits
Search building permits by location, date, category, contractor and more.
Filters combine with AND. Supply at least one narrowing filter -- a city, ZIP,
jurisdiction, date range or lat/lng radius -- for a query that returns quickly.
Results are paginated and ordered newest-first on the permit's best available date
(`date_issued`, falling back to `date_filed`). `total` is exact up to 10,000; beyond
that it stops counting and returns `total: 10000` with `total_capped: true`, meaning
"10,000 or more". If the count cannot finish in time the response carries
`total: null` with `total_unknown: true` -- an unknown total is reported as unknown
and never as a number. Rows are unaffected either way; page through them normally.
`category=hvac` matches HVAC and MECHANICAL together, because AC and furnace work is
filed under either depending on the city. Unknown parameter names are rejected with a
400 rather than ignored, so a typo can never silently return unfiltered results.
Free-tier keys are limited to a recent window; paid tiers have full history.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
zip_code | string | 5-digit ZIP code |
city | string | City name |
state | string | 2-letter state code |
jurisdiction | string | Jurisdiction name (e.g. 'Wake County', 'Tacoma') or partial match |
address | string | Street address, partial + case-insensitive (e.g. '1600 Pennsylvania') - indexed, fast |
lat | number | Latitude for radius search |
lng | number | Longitude for radius search |
radius_miles | number | Radius in miles (used with lat/lng) default: 5.0 |
fields | string | 'summary' (default) or 'full'. With 'full' each result is a PermitDetail rather than a PermitSummary -- the same nine extra columns GET /v1/permits/{id} returns (record_kind, date_expired, fee_amount, stories, units, square_footage, applicant_name, contractor_license, created_at) -- so you do not fetch them one permit at a time. See the PermitDetail schema for their types; the declared response schema here is PermitSummary, which is the default shape. Developer plan and above, or record credits without owner data. default: "summary" |
bbox | string | Map-viewport bounding box 'minLng,minLat,maxLng,maxLat'. Returns permits whose location falls inside the box (geocoded permits only). |
polygon | string | A drawn area as a GeoJSON Polygon geometry (URL-encoded), e.g. {"type":"Polygon","coordinates":[[[lng,lat],...]]}. Returns permits inside the polygon (geocoded permits only). |
category | string | Permit category (e.g. solar, SOLAR, roofing, hvac - case insensitive) |
status | PermitStatus | Permit status (e.g. issued, filed, final) |
property_type | PropertyType | Property type (e.g. residential, commercial) |
tag | string | Filter by tag |
record_kind | string | Record kind: 'permit' (default, building permits only), 'contractor', 'tag', 'non_building', 'admin', 'program' (incentive-program records counted through another dataset, e.g. NYSERDA NY-Sun), or 'all' default: "permit" |
filed_after | string | Filed on or after this date |
filed_before | string | Filed on or before this date |
issued_after | string | Issued on or after this date |
issued_before | string | Issued on or before this date |
date_after | string | On or after this date, matched against whichever date a record has (issued, else filed). Use this when a source populates only one of issued/filed - e.g. issued-only feeds vs filed-only feeds. |
date_before | string | On or before this date, matched against whichever date a record has (issued, else filed). |
parcel | string | Parcel number / APN / folio (formatting ignored). Returns permits on that parcel where the source publishes one. |
min_value | number | Minimum estimated value |
max_value | number | Maximum estimated value |
min_solar_kw | number | Minimum extracted solar system size (kW DC) |
max_solar_kw | number | Maximum extracted solar system size (kW DC) |
min_sqft | number | Minimum square footage mentioned (from enrichment) |
has_enrichment | boolean | Only permits that have (true) or lack (false) LLM enrichment |
scope | string | Substring match on the enriched work scope |
q | string | Case-insensitive substring match across description, address, and permit number. Terms under 3 characters are matched but not counted: `total` is null with total_unknown=true (a 1-2 character term has no trigram index and the count would cost tens of seconds). |
permit_number | string | Exact permit number as the issuing jurisdiction assigned it, case-insensitive (surrounding spaces ignored). Narrower and much faster than q= for a known number. The same number can exist in more than one jurisdiction, so add city or state to tell them apart. |
contractor_name | string | Contractor name (partial match) |
owner_filed | boolean | true selects records with no linked contractor and a recorded owner name, using source contractor coverage checks; false selects records with a linked contractor. This filter does not verify who filed, homeowner status or purchase intent. |
has_owner_address | boolean | true = only permits that carry a property-owner mailing address; false = only those that do not. Coverage varies sharply by jurisdiction (we hold the county assessor roll for some and not others), so this is a targeting filter rather than a defect: it returns exactly the rows that are actionable. The address itself is visible on Business and above. |
page | integer | default: 1 |
per_page | integer | Results per page. Above your plan's maximum this is clamped, not rejected; the response echoes the per_page actually applied. default: 25 |
keyword | string | Alias of `q`. |
date_from | string | Alias of `date_after`. |
date_to | string | Alias of `date_before`. |
start_date | string | Alias of `date_after`. |
end_date | string | Alias of `date_before`. |
limit | integer | Alias of `per_page`. Clamped to your plan's maximum, not rejected. |
count_only | boolean | Return only the total for these filters -- no permit records. Skips the row fetch entirely, so it is markedly cheaper for both of us when you are sizing a query rather than reading it. `results` comes back empty and `total_capped` / `total_unknown` mean exactly what they always do. default: false |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitSearchResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | PermitSummary[] | |
hints | Hint[] | |
coverage_confidence | CoverageConfidence | |
tier_window_days | integer | |
tier_window_from | string | |
tier_window_clamped | boolean | |
tier_window_upgrade_url | string | |
locked_fields | string[] | |
locked_upgrade_url | string | |
coverage | JurisdictionCoverage[] | |
total_capped | boolean | |
total_unknown | boolean |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/permits/search"
GET/v1/permits/stats/coverage
Get Coverage Stats
Coverage statistics: total permits, every jurisdiction we hold, and the counties they fall in.
Each jurisdiction carries nullable `data_through` (the newest held permit date where measured),
plus `county` / `county_fips` (the county most of its permits fall in) and `counties`
(the full measured mix with a `share` of the sample per county, since some cities straddle
a county line). `counties` at the top level is the same data keyed by county, listing the
jurisdictions whose permits fall in each one. A null county means not measured, which is
the case for statewide feeds that publish no coordinates.
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/permits/stats/coverage"
GET/v1/permits/sync
Sync Permits
Incremental data feed (change-data-capture). Page the dataset ordered by
(updated_at, id). Omit `cursor` for the initial full load; persist `next_cursor` and pass
it back after each nightly ingest to receive only new + changed permits. Upsert-only:
permits we delete (duplicate copies removed in cleanups) are listed separately by
GET /v1/permits/sync/deletions, which pages the same way.
**Keeping a mirror exact.** Upsert every record from this feed, and drop every
`permit_id` that GET /v1/permits/sync/deletions returns when called with the SAME
`record_kind`, `state` and `category` you pass here. A permit can leave a filtered
feed without being deleted -- re-classified (roofing -> hvac), re-located to another
state, re-labelled as a non-building record, or its source switched off -- and the
deletions feed then lists it for every filter it no longer matches, and never for one
it still matches. A permit that moves INTO your filter arrives here with a new
`updated_at`. Membership changes are recorded from 2026-10-25; category and state moves
before that date were not, so a mirror built with `category=` or `state=` before then
should re-pull once (or sync unfiltered with `record_kind=all` and filter locally).
Parameters
| Name | Type | Description |
|---|---|---|
cursor | string | Opaque cursor from the previous response's `next_cursor`. Omit to start the initial full sync from the beginning. |
since | string | Alternative start point: an ISO-8601 UTC timestamp; returns permits with updated_at >= since. Ignored when `cursor` is supplied. |
limit | integer | Max permits per page (cursor page size, up to 50,000). default: 5000 |
record_kind | string | 'permit' (default), a specific record_kind, or 'all'. default: "permit" |
state | string | Optional 2-letter state filter to scope the feed. |
category | string | Optional category filter (e.g. solar, roofing). |
fields | string | 'summary' (default) or 'full'. 'full' adds record_kind, date_expired, fee_amount, stories, units, square_footage, applicant_name, contractor_license and created_at to every record, so a mirror does not have to fetch them one permit at a time. Both shapes include location_source and nullable location_precision. location_precision is an additive field introduced with the geocode quality update; consumers must allow nullable/additive fields. default: "summary" |
Responses
| Code | Meaning |
|---|---|
200 | A page of permits in (updated_at, id) order. Keep `next_cursor` and pass it back as `cursor` to resume; `has_more` is false once you are caught up. Each record in `results` has the /v1/permits/search fields (fields=summary) plus the extras listed under `fields=full`. Page size is `limit`, up to 50,000. |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/permits/sync"
GET/v1/permits/sync/deletions
Sync Deletions
Permits to drop from a mirror built with /v1/permits/sync.
/v1/permits/sync is upsert-only, so a permit we delete (almost always a duplicate copy of a
permit that still exists under another id) would otherwise live on in a mirror and 404 on
/v1/permits/{id}. Drop every `permit_id` listed here. Same cursor contract as /sync: omit
`cursor` (or pass `since`) to start, then pass back `next_cursor`. When the deleted copy's
permit still exists under another id, `replaced_by` names it. Every delete is recorded by a
database trigger, so this list covers all deletions from 2026-09-24 on, whatever removed them.
**Call it with the same `record_kind`, `state` and `category` as your /v1/permits/sync
calls.** It also lists permits that LEFT that feed without being deleted (`kind =
"left_feed"`, the permit still exists): we stopped serving the source
(`reason = "jurisdiction_deactivated"`), it was re-labelled as a non-building
record (`left_permit_set:<kind>`, or `record_kind_changed:<kind>` for a
record that was not a permit), or -- from 2026-10-25 -- it was re-classified or moved to
another state or source (`category_changed:OLD->NEW`,
`state_changed:OLD->NEW`, `jurisdiction_changed`; for a move,
`jurisdiction_id` is the source it LEFT and `moved_to_jurisdiction_id` the one it joined).
`reason` names the latest change, except that a re-label or a stopped source still in
force keeps its reason through later changes. Each entry is judged against the permit as it is
NOW: one that still matches your filters is never listed for you, and one that comes back
is re-sent by /v1/permits/sync with a new `updated_at`.
A page holds at most `limit` results. To reach them it examines records past ones that do
not concern you (up to 250,000 per page), so after a large
re-classification a page can still hold fewer than `limit` results, even none, while
`has_more` is true. Keep paging until `has_more` is false; `next_cursor` always advances
past everything examined.
Parameters
| Name | Type | Description |
|---|---|---|
cursor | string | Opaque cursor from the previous response's `next_cursor`. |
since | string | ISO-8601 UTC timestamp; returns deletions with deleted_at >= since. Ignored when `cursor` is supplied. Omit both to page every recorded deletion. |
limit | integer | Max results per page (up to 50,000). A page can return fewer -- even none -- and still have `has_more`: keep paging while `has_more` is true. default: 5000 |
record_kind | string | Pass the same value you pass to /v1/permits/sync: 'permit' (default), a specific record_kind, or 'all'. A permit re-labelled as a non-building record is listed for record_kind=permit and not for record_kind=all, where it is still in the feed. default: "permit" |
state | string | Pass the same 2-letter state you pass to /v1/permits/sync. Lists permits that left that state's feed, including ones whose own address_state differs from their jurisdiction's. |
category | string | Pass the same category you pass to /v1/permits/sync. Lists permits re-classified out of it (e.g. roofing -> hvac) as well as deletions. |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/permits/sync/deletions"
GET/v1/permits/{permit_id}
Get Permit
Get full details for a single permit.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
permit_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitDetail
| Field | Type | Description |
|---|---|---|
idrequired | string | Stable PermitStack id. Pass to GET /v1/permits/{id}."f4be62ed-b522-42a3-907b-b4ab4ec1a102" |
permit_numberrequired | string | The permit number as the issuing jurisdiction publishes it. Not unique across jurisdictions, and not always present."R2608-181" |
statusrequired | enum | One of FILED, ISSUED, IN_PROGRESS, FINAL, EXPIRED, CANCELLED, REVOKED, INTERCONNECTED, UNKNOWN -- normalised by us from each source's own vocabulary. UNKNOWN means no recognized normalized status is available; the source value may be missing or unrecognized. It does not establish whether the permit is active. INTERCONNECTED comes from the California NEM solar feed. FILED · ISSUED · IN_PROGRESS · FINAL · EXPIRED · CANCELLED · REVOKED · UNKNOWN · INTERCONNECTED "ISSUED" |
categoryrequired | enum | Trade/work classification, UPPERCASE. One of: NEW_CONSTRUCTION, RENOVATION, DEMOLITION, ELECTRICAL, PLUMBING, MECHANICAL, ROOFING, SOLAR, BATTERY, EV_CHARGER, HVAC, FIRE_ALARM, SIGN, FENCE, POOL, FOUNDATION, ADDITION, INTERIOR_REMODEL, GRADING, OTHER. Derived by us from the permit type and description, not published by the city. NOTE when FILTERING: ?category=hvac matches HVAC *and* MECHANICAL, and ?category=mechanical does the same, because HVAC work is routinely filed as MECHANICAL -- they are one market and a bare equality would hide half of it. NEW_CONSTRUCTION · RENOVATION · DEMOLITION · ELECTRICAL · PLUMBING · MECHANICAL · ROOFING · SOLAR · BATTERY · EV_CHARGER · HVAC · FIRE_ALARM · SIGN · FENCE · POOL · FOUNDATION · ADDITION · INTERIOR_REMODEL · GRADING · OTHER "ROOFING" |
tagsrequired | string[] | Free-form keywords extracted from the description (e.g. 'pool', 'reroof'). Additive; do not rely on a fixed vocabulary.["pool"] |
property_typerequired | string | RESIDENTIAL, COMMERCIAL, INDUSTRIAL, MIXED_USE or UNKNOWN. UNKNOWN means no recognized normalized property type is available. Source omissions, mapping gaps or unrecognized values can cause this."RESIDENTIAL" |
address_streetrequired | string | Held street address mapped from source fields. It may be assembled from components or split from a postal address; spacing can vary. Address matching normalises whitespace."288 Mosaic Blvd" |
address_cityrequired | string | City recorded for this held permit. Null means no usable normalized city is available; it does not establish that the property is outside a city or that the source never publishes one."Daytona Beach" |
address_staterequired | string | 2-letter state recorded for this held permit. Null means no usable normalized state is available. A state search can still include such rows using independent jurisdiction evidence."FL" |
address_ziprequired | string | 5-digit ZIP where published."32124" |
parcel_id | string | Assessor parcel number / APN, either published with the permit or matched from an appraiser roll by situs address. Formatting varies by source and is preserved. Null means no usable parcel is mapped on this record; it does not establish that the upstream feed or property has no parcel. Filterable via ?parcel= after the parcel index is refreshed."521804000160" |
description_rawrequired | string | Held source-derived work description. Text may be combined from multiple fields, cleaned, or have contacts removed. Whole-value placeholders may become null. Used by the category classifier; not a verbatim copy or evidence that work was completed."RE-ROOF: remove existing shingles, install 39 sq architectural shingles" |
estimated_valuerequired | number | Declared job value in USD, as published. Frequently null and occasionally nominal -- treat 0 and 1 as 'not stated'.24500.0 |
date_filedrequired | string | Application/filing date where mapped and usable. Null means no usable held filing date is available; source omissions, mapping gaps or validation can cause this."2026-08-14" |
date_issuedrequired | string | Issue date where mapped and usable. Null means no usable held issue date is available; it does not establish what dates the source publishes. date_after/date_before filter on COALESCE(date_issued, date_filed); issued_after uses only date_issued."2026-08-21" |
date_completedrequired | string | Completion/final date where the source publishes one. Usually null. |
approval_days | integer | Calendar days from date_filed to date_issued (null unless both dates present) |
construction_days | integer | Calendar days from date_issued to date_completed (null unless both dates present) |
contractor_name | string | Contractor name linked to the held permit record after cleaning and matching. Null values can reflect source omissions, mapping gaps or unmatched names. The jurisdiction_coverage block reports contractor-name presence on the current page; it does not prove complete source capture. |
contractor_id | string | Opaque id of the contractor linked to this held permit. Use GET /v1/contractors/{id} for its record. Null means no contractor is linked; source omissions and matching gaps can both cause this. |
owner_name | string | Owner name recorded by the source, subject to field access. A present owner name and absent contractor name do not establish who filed the permit, a homeowner, purchase intent or a sales opportunity. Source omissions and matching gaps can explain missing contractor data. Review the owner_filed filter semantics and source coverage. |
owner_address | string | Property-owner mailing address. Business plan ($149/mo) and above; null below that access gate. Joined from held county assessor records by parcel. Source availability, capture and matching vary by jurisdiction; loading a roll does not establish complete address coverage. A null value does not establish that a property has no owner on record. |
jurisdiction_name | string | The PermitStack data source this permit came from -- a city, county or statewide feed, which is not always the permit's own city."Daytona Beach" |
latitude | number | WGS84 latitude. Null means no usable latitude is held after mapping and any geocoding; it does not establish that the source lacks coordinates. Permits without usable coordinates are absent from radius, bbox and polygon search.29.1872 |
longitude | number | WGS84 longitude.-81.0559 |
location_source | enum | Coordinate provenance. 'source' = recorded publisher coordinates, or a legacy feed-level attribution; 'geocoded' = our point with recorded ownership or an audited legacy ownership classification; 'derived' = the method is unclassified from available provenance. Older unlogged TIGER interpolations can read 'derived' or, in coordinate-publishing feeds, 'source' until audited. No value guarantees a structure or parcel-centroid location. Null when coordinates are null. See location_precision. source · geocoded · derived "source" |
location_precision | enum | 'source' = publisher's coordinates (accuracy varies); 'address_point' = an exact normalized-address match to agreeing source points; 'street_interpolated' = TIGER address-range interpolation, possibly offset toward the matched street side; 'legacy_street_interpolated' = an older point classified as TIGER under the legacy ownership rule (non-publishing feed, existing attempt marker, no source-coordinate or other-writer evidence). Geometric proximity alone never establishes ownership; unclassified attempt markers have null precision. No value guarantees a particular structure position. Null when coordinates or their method are unknown. Legacy source attribution is subject to the location_source caveat. source · address_point · street_interpolated · legacy_street_interpolated "street_interpolated" |
enrichment | PermitEnrichment | Structured detail parsed from the description (e.g. solar kW) where we could extract it. Null for most permits. |
record_kind | string | permit | contractor | tag | non_building | admin. Some portals mix non-permit records (contractor registrations, right-of-way, administrative) into the same feed; we store them and label them rather than counting them as permits. Search and export return record_kind='permit' only unless you ask otherwise."permit" |
date_expiredrequired | string | Expiry date where published. Deliberately NOT null-checked against the future the way the other dates are -- an expiry legitimately lies ahead."2027-02-21" |
fee_amount | number | Permit/inspection fee where mapped and usable. A null value does not establish that the source never publishes fees or that no fee was charged. |
storiesrequired | integer | Building stories, where published.1 |
unitsrequired | integer | Dwelling/tenant units, where published.1 |
square_footagerequired | number | Project square footage, where published. Usually null.2100.0 |
applicant_namerequired | string | Whoever filed the application. On most feeds this is the OWNER; on a few it is the contractor, and for those tenants we map it to contractor_name instead. Never assume which one it is from this field alone. |
contractor_license | string | Contractor's licence number as published or as matched against a state licence-board roster. A free public identifier; contact details remain gated to /v1/contractors/{id} on Developer+."CBC1262595" |
created_at | string | When PermitStack first ingested this record (ISO 8601). NOT a date the city published -- use date_filed/date_issued for that."2026-08-22T04:11:03.882174+00:00" |
PermitEnrichment
| Field | Type | Description |
|---|---|---|
scope | string | |
work_summary | string | |
solar_kw | number | |
sqft | number | |
units | integer | |
is_residential | boolean | |
is_commercial | boolean | |
materials | string[] |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/permits/{permit_id}"GET/v1/plays
List Plays
List available trade plays and their parameters.
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/plays"
GET/v1/plays/battery-retrofit-candidates
Battery Retrofit Candidates
Search held solar permit records in the selected permit-age range with no
matching battery-tagged permit found at the same recorded address. Dates use
issue date, falling back to filing date. Requires a location filter; results
are paginated and depend on source coverage, classification and address matching.
An absent match does not establish that a property lacks a battery. Permit
dates do not verify installation or current equipment. Review scope,
completion and equipment suitability before assessing retrofit needs.
Parameters
| Name | Type | Description |
|---|---|---|
state | string | 2-letter state code |
city | string | City name |
zip_code | string | 5-digit ZIP |
jurisdiction | string | Jurisdiction name (partial) |
min_age_years | number | Minimum age of the PV permit, in years default: 2 |
max_age_years | number | Maximum age of the PV permit, in years default: 7 |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitSearchResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | PermitSummary[] | |
hints | Hint[] | |
coverage_confidence | CoverageConfidence | |
tier_window_days | integer | |
tier_window_from | string | |
tier_window_clamped | boolean | |
tier_window_upgrade_url | string | |
locked_fields | string[] | |
locked_upgrade_url | string | |
coverage | JurisdictionCoverage[] | |
total_capped | boolean | |
total_unknown | boolean |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/plays/battery-retrofit-candidates"
GET/v1/plays/orphan-recovery
Orphan Recovery
Search held solar permit records using a case-insensitive substring match
in recorded contractor, applicant or owner fields. Requires a location filter;
results are paginated and depend on source coverage and available names.
A name match does not verify the installer, a customer relationship, completed
installation or current service needs. Review identity, project scope,
completion and current equipment before using a result as a prospect.
Parameters
| Name | Type | Description |
|---|---|---|
installerrequired | string | Installer name to match (contractor/applicant/owner) |
state | string | 2-letter state code |
city | string | City name |
zip_code | string | 5-digit ZIP |
jurisdiction | string | Jurisdiction name (partial) |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitSearchResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | PermitSummary[] | |
hints | Hint[] | |
coverage_confidence | CoverageConfidence | |
tier_window_days | integer | |
tier_window_from | string | |
tier_window_clamped | boolean | |
tier_window_upgrade_url | string | |
locked_fields | string[] | |
locked_upgrade_url | string | |
coverage | JurisdictionCoverage[] | |
total_capped | boolean | |
total_unknown | boolean |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/plays/orphan-recovery"
GET/v1/plays/reroof-due
Reroof Due
Search held roofing permit records in the selected permit-age range, with
no newer matching roofing record found at the same recorded address. Dates use
issue date, falling back to filing date. Results are paginated and depend on
source coverage, classification and address matching.
A roofing record can describe a repair or proposed work. Its age does not
establish roof age or predict replacement, and missing records do not prove
that no later work occurred. Review scope, completion and current condition.
Alias of /v1/plays/system-age?trade=roofing.
Parameters
| Name | Type | Description |
|---|---|---|
state | string | 2-letter state code |
city | string | City name |
zip_code | string | 5-digit ZIP |
jurisdiction | string | Jurisdiction name (partial) |
min_age_years | number | Minimum age of the roofing permit, in years default: 12 |
max_age_years | number | Maximum age of the roofing permit, in years default: 25 |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitSearchResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | PermitSummary[] | |
hints | Hint[] | |
coverage_confidence | CoverageConfidence | |
tier_window_days | integer | |
tier_window_from | string | |
tier_window_clamped | boolean | |
tier_window_upgrade_url | string | |
locked_fields | string[] | |
locked_upgrade_url | string | |
coverage | JurisdictionCoverage[] | |
total_capped | boolean | |
total_unknown | boolean |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/plays/reroof-due"
GET/v1/plays/system-age
System Age
Search held permit records by trade and permit age. The date basis is issue
date, falling back to filing date. The query selects the newest matching held
record at a recorded address within the selected age range, with no newer
matching record found. Supported trades: roofing, hvac, mechanical, solar and pool.
Results are paginated and depend on source coverage, classification and address
matching. A missing newer record does not establish that no later work occurred.
These dates do not verify installation, equipment age or replacement needs.
Review work scope, completion evidence and current condition separately.
Parameters
| Name | Type | Description |
|---|---|---|
traderequired | string | roofing | hvac | mechanical | solar | pool |
state | string | 2-letter state code |
city | string | City name |
zip_code | string | 5-digit ZIP |
jurisdiction | string | Jurisdiction name (partial) |
min_age_years | number | Override the trade's default minimum age |
max_age_years | number | Override the trade's default maximum age |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitSearchResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | PermitSummary[] | |
hints | Hint[] | |
coverage_confidence | CoverageConfidence | |
tier_window_days | integer | |
tier_window_from | string | |
tier_window_clamped | boolean | |
tier_window_upgrade_url | string | |
locked_fields | string[] | |
locked_upgrade_url | string | |
coverage | JurisdictionCoverage[] | |
total_capped | boolean | |
total_unknown | boolean |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/plays/system-age"
Property History
Get permit history for a specific address
GET/v1/property/by-parcel
Get Property By Parcel
Held permit history and a derived profile for a parcel / APN.
Searches stored parcel identifiers with supported formatting normalization.
Pass `state` to narrow reused parcel numbers. Missing or inconsistent source
identifiers can prevent a match; use /property/history by address as another
lookup. Review `distinct_addresses` and `fan_out_warning` for multi-address
parcels before treating a profile as one property.
Results depend on coverage, matching and the plan's history window. Permit
records are paginated; `truncated` identifies capped contractor and jurisdiction
profile lists. Date signals prefer issue date, then filing date, then completion
date where available. They are permit-date proxies, not verified installation,
replacement or present-condition evidence.
No matching records returns `found: false` (HTTP 200). Inspect the coverage
block and capture note; a miss does not establish that no permit or work exists.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
parcelrequired | string | Parcel number / APN / folio. Formatting is ignored - dashes, dots and spaces are stripped before matching. |
state | string | Optional 2-letter state to disambiguate the same parcel number across counties |
page | integer | default: 1 |
per_page | integer | default: 50 |
limit | integer | Alias of per_page. |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PropertyHistoryResponse
| Field | Type | Description |
|---|---|---|
queryrequired | PropertyQuery | |
foundrequired | boolean | |
total_matchesrequired | integer | |
truncatedrequired | boolean | |
distinct_addresses | integer | |
distinct_jurisdictions | integer | |
fan_out_warning | string | |
summaryrequired | PropertySummary | |
coverage | CoverageConfidence | |
data_currency | JurisdictionCoverage[] | |
pagerequired | integer | |
per_pagerequired | integer | |
has_morerequired | boolean | |
permitsrequired | PermitSummary[] |
PropertyQuery
| Field | Type | Description |
|---|---|---|
address | string | |
parcel | string | |
city | string | |
state | string | |
zip | string |
PropertySummary
| Field | Type | Description |
|---|---|---|
total_permitsrequired | integer | |
first_permit_date | string | |
last_permit_date | string | |
years_of_history | integer | |
total_estimated_value | number | |
categoriesrequired | object | |
jurisdictionsrequired | string[] | |
contractorsrequired | string[] | |
signalsrequired | PropertySignals |
PropertySignals
| Field | Type | Description |
|---|---|---|
has_solar | boolean | |
solar_kw | number | |
last_solar_date | string | |
has_battery | boolean | |
last_battery_date | string | |
has_roofing | boolean | |
last_roofing_date | string | |
has_pool | boolean | |
last_pool_date | string | |
has_addition | boolean | |
has_new_construction | boolean | |
has_electrical | boolean | |
has_hvac | boolean | |
last_hvac_date | string | |
has_plumbing | boolean | |
has_demolition | boolean | |
last_activity_date | string |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/property/by-parcel"
GET/v1/property/history
Get Property History
Held permit history and a derived profile for an address.
Searches stored permit addresses using the supplied address and optional
`city`/`state`/`zip` filters. Results depend on source coverage, address
matching and the plan's history window. Follow pagination for permit records;
`truncated` identifies capped contractor and jurisdiction profile lists.
Category and date signals describe matching permit records. Date signals
prefer issue date, then filing date, then completion date where available;
they do not verify installation, replacement or current property condition.
No matching records returns `found: false` with an empty profile (HTTP 200).
Inspect the coverage block and capture note. A miss is not proof that no
permit or work exists, even where a source is current.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
addressrequired | string | Street address to look up (e.g. '123 Main St') |
city | string | Optional city to disambiguate identical street addresses |
state | string | Optional 2-letter state code |
zip | string | Optional ZIP (prefix-matched) |
page | integer | default: 1 |
per_page | integer | default: 50 |
limit | integer | Alias of per_page. |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PropertyHistoryResponse
| Field | Type | Description |
|---|---|---|
queryrequired | PropertyQuery | |
foundrequired | boolean | |
total_matchesrequired | integer | |
truncatedrequired | boolean | |
distinct_addresses | integer | |
distinct_jurisdictions | integer | |
fan_out_warning | string | |
summaryrequired | PropertySummary | |
coverage | CoverageConfidence | |
data_currency | JurisdictionCoverage[] | |
pagerequired | integer | |
per_pagerequired | integer | |
has_morerequired | boolean | |
permitsrequired | PermitSummary[] |
PropertyQuery
| Field | Type | Description |
|---|---|---|
address | string | |
parcel | string | |
city | string | |
state | string | |
zip | string |
PropertySummary
| Field | Type | Description |
|---|---|---|
total_permitsrequired | integer | |
first_permit_date | string | |
last_permit_date | string | |
years_of_history | integer | |
total_estimated_value | number | |
categoriesrequired | object | |
jurisdictionsrequired | string[] | |
contractorsrequired | string[] | |
signalsrequired | PropertySignals |
PropertySignals
| Field | Type | Description |
|---|---|---|
has_solar | boolean | |
solar_kw | number | |
last_solar_date | string | |
has_battery | boolean | |
last_battery_date | string | |
has_roofing | boolean | |
last_roofing_date | string | |
has_pool | boolean | |
last_pool_date | string | |
has_addition | boolean | |
has_new_construction | boolean | |
has_electrical | boolean | |
has_hvac | boolean | |
last_hvac_date | string | |
has_plumbing | boolean | |
has_demolition | boolean | |
last_activity_date | string |
CoverageConfidence
| Field | Type | Description |
|---|---|---|
confidencerequired | string | |
coveredrequired | boolean | |
jurisdiction | string | |
data_status | string | |
data_through | string | |
freshness | string | |
jurisdiction_permit_count | integer | |
noterequired | string | |
tier_window_days | integer | |
tier_window_from | string | |
capture_ratio | number | |
capture_checked_at | string | |
capture_note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/property/history"
Contractors
Search contractors and see their permit history
GET/v1/contractors/search
Search Contractors
Search contractors by name, location, or specialty, ranked by activity score.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | Contractor name (partial match) |
state | string | 2-letter state code |
city | string | City name |
specialty | string | Specialty tag (e.g. solar, roofing, hvac) |
license_number | string | Exact state licence number, e.g. 'CBC1262595'. Matched exactly, and also tried uppercased -- so any capitalisation works for the licences stored uppercase, which is 99.96% of them. Combine with license_state when the same number is issued in more than one state. |
license_state | string | 2-letter state that ISSUED the licence. Not the same as `state`, which is where the contractor pulls permits. |
min_permits | integer | Minimum total permits |
min_score | integer | Minimum contractor activity score (0-100) |
sort | string | Sort order: 'score' (default), 'permits', or 'recent' default: "score" |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
ContractorSearchResponse
| Field | Type | Description |
|---|---|---|
totalrequired | integer | |
pagerequired | integer | |
per_pagerequired | integer | |
resultsrequired | ContractorSummary[] | |
specialties_matched | string[] |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/contractors/search"
GET/v1/contractors/{contractor_id}
Get Contractor
Get a contractor's full profile with permit stats.
`phone`, `email` and the street `address` are contractor contact fields gated to the
Developer plan and up (see /v1/billing/plans for current pricing); on free/indie/hobbyist
they return null and `locked_fields` names them. `name`, `license_number`, `specialties`,
`city`/`state`/`zip_code`, and the stats are available on all plans.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
contractor_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
ContractorProfile
| Field | Type | Description |
|---|---|---|
idrequired | string | |
namerequired | string | |
license_numberrequired | string | |
license_staterequired | string | |
cityrequired | string | |
staterequired | string | |
total_permitsrequired | integer | |
first_permit_daterequired | string | |
last_permit_daterequired | string | |
specialtiesrequired | string[] | |
score | integer | |
is_business | boolean | |
phonerequired | string | |
emailrequired | string | |
contact_locked | boolean | |
locked_fields | string[] | |
upgrade_url | string | |
withheld_fields | string[] | |
addressrequired | string | |
zip_coderequired | string | |
recent_categories | string[] | |
avg_project_value | number |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/contractors/{contractor_id}"GET/v1/contractors/{contractor_id}/permits
Get Contractor Permits
Search a page of held permit records linked to a contractor. Source coverage,
available names and contractor matching affect results; these records are not
a complete project history or proof of completed work.
Free keys created after the grandfathering cutoff (free_new) see only their recent
window, exactly as on /v1/permits/search and /v1/property/history, and the page is
capped at their tier's max_per_page. Paid and grandfathered (free_legacy) keys see the
held history without that date restriction, subject to pagination and coverage.
The window is stated in the X-PermitStack-Date-Window-*
headers, the same additive signal property history uses.
Record credits: when there is no active plan entitlement, one credit is charged per returned record, with a one-credit minimum for successful empty data responses. Property responses count their permits. CSV sizing previews cost 0 credits and share the per-key 60/minute request budget. Credit accounts cannot receive owner or contractor contact fields. An empty or expired wallet returns 402 with a pack URL before the data query. Concurrent requests for the same wallet can return 409; retry after one second. A final JSON page may overdraw once; the next purchase first covers that debt. CSV downloads are capped at the remaining credit balance.
Parameters
| Name | Type | Description |
|---|---|---|
contractor_idrequired | string | |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
402 | Record credits empty or expired |
409 | Wallet busy, or CSV count/cost changed |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/contractors/{contractor_id}/permits"Licensing
Contractor licence records as public state licence boards publish them: licence number, type, class, status and dates. Look one up by number and state, or list the licences linked to a contractor. Contractor licensing add-on, $19/mo on Developer; included in Business and Scale. Bond, liability insurance, workers' comp and discipline fields need Contractor licensing Pro (only some boards publish them): Contractor licensing Pro add-on, $29/mo on Developer or Business; included in Scale. No phone, email or street address is returned here.
Start with the dataset coverage, fields and plan access. Authenticate with X-API-Key; enable the dataset in your dashboard.
Make your first request
Synthetic licence identifier example, not a captured response. Status, expiry and Pro values are available after authentication and are not reproduced on this public page.
curl
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/licenses/lookup?license_number=EXAMPLE-0001&state=TX"
Python
import os
import requests
response = requests.get(
"https://api.permit-stack.com/v1/licenses/lookup?license_number=EXAMPLE-0001&state=TX",
headers={"X-API-Key": os.environ["PERMITSTACK_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json())Response excerpt
{
"licenses": [
{
"source": "EXAMPLE_BOARD",
"issuing_state": "TX",
"license_number": "EXAMPLE-0001",
"classification": "GENERAL"
}
]
}GET/v1/contractors/{contractor_id}/licenses
Get Contractor Licenses
Licences the public licence boards publish for one contractor.
A licence is linked by the contractor's licence number in the board's issuing state (the
names must also agree -- licence-number spaces collide across boards -- except in
Washington L&I's roster, where a number on one row is enough), or by the contractor's exact
normalised name in its state where that name is unique in the board's roster. A
registration (record_kind "registration") is linked by name only. No fuzzy matching. Bond,
insurance, workers' comp and discipline are Licensing Pro fields. Contact data is not part
of this dataset.
Parameters
| Name | Type | Description |
|---|---|---|
contractor_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
ContractorLicensesResponse
| Field | Type | Description |
|---|---|---|
accessrequired | string | |
licensesrequired | LicenseRecord[] | |
totalrequired | integer | |
locked_fields | string[] | |
upgrade_url | string | |
contractor_idrequired | string | |
contractor_name | string | |
note | string |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/contractors/{contractor_id}/licenses"GET/v1/licenses/lookup
Lookup License
One licence number in one issuing state, as every roster we hold for that state
publishes it, plus the contractors in our permit data carrying that licence number.
Parameters
| Name | Type | Description |
|---|---|---|
license_numberrequired | string | Licence number as issued (spaces, dashes and case are ignored) |
staterequired | string | 2-letter issuing state |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
LicenseLookupResponse
| Field | Type | Description |
|---|---|---|
accessrequired | string | |
licensesrequired | LicenseRecord[] | |
totalrequired | integer | |
locked_fields | string[] | |
upgrade_url | string | |
license_numberrequired | string | |
staterequired | string | |
contractorsrequired | LinkedContractor[] |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/licenses/lookup"
Certificates of Occupancy
Certificates of occupancy as cities, counties and state agencies publish them: certificate number, type, status and date, address, parcel, occupancy class, units and the linked permit where we hold it. /v1/certificates/coverage works with any API key, so you can check a place before buying. Certificates of occupancy add-on, $29/mo on Developer; included in Business and Scale.
Start with the dataset coverage, fields and plan access. Authenticate with X-API-Key; enable the dataset in your dashboard.
Make your first request
Synthetic occupancy-certificate example, not a captured response. Personal names, contact details and street addresses are omitted.
curl
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/certificates/00000000-0000-4000-8000-000000000001"
Python
import os
import requests
response = requests.get(
"https://api.permit-stack.com/v1/certificates/00000000-0000-4000-8000-000000000001",
headers={"X-API-Key": os.environ["PERMITSTACK_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json())Response excerpt
{
"id": "00000000-0000-4000-8000-000000000001",
"kind": "occupancy",
"certificate_status": "issued",
"co_date": null
}GET/v1/certificates/coverage
Certificate Coverage
Which places we hold certificates for, and how current each is. Any API key can call it,
so a buyer can check a city before adding the dataset, like /v1/jurisdictions.
One row per (source, place); a statewide source (CA HCD) lists each city and county it
reports for, plus one `(no city published)` row per state for its lines that name no city
(reachable with `state=`, not `city=`). `records` counts canonical issued certificates of
occupancy, renewals excluded: exactly what a default search returns, and `data_through` /
`freshness` describe those same certificates. `completion_records`,
`completion_data_through` and `completion_freshness` describe certificates of completion
(kind=completion) on their own. `data_status` says whether the source still publishes
(active / historical_archive / frozen); for a permits-derived source,
`source_data_through` is the newest record of the permits feed the certificates come from,
which bounds an undated source's currency.
Parameters
| Name | Type | Description |
|---|---|---|
state | string | 2-letter state code |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/certificates/coverage"
GET/v1/certificates/search
Search Certificates
Search certificates of occupancy (and, with kind=completion, certificates of completion).
Each result carries `co_date_basis`, which says what its date means, and every response lists
the sources it drew from with their measured `data_through`, `dated_share` and (where the
source publishes a total) `completeness`. Add-on dataset: included in Business and Scale,
available as an add-on on Developer.
Parameters
| Name | Type | Description |
|---|---|---|
city | string | City name (matches the address city or the issuing jurisdiction) |
state | string | 2-letter state code |
zip_code | string | 5-digit ZIP |
jurisdiction_id | string | A jurisdiction id from /v1/jurisdictions |
address | string | Street address, partial, case-insensitive |
parcel | string | Parcel / APN / folio / BBL (formatting ignored) |
lat | number | |
lng | number | |
radius_miles | number | Radius in miles around lat/lng (default 1) |
kind | enum | 'occupancy' (default), 'completion' (certificates of completion: close-outs of work that creates no occupancy, e.g. roofs, pools), or 'all' occupancy · completion · all default: "occupancy" |
co_type | enum | 'change' = re-issued for an existing building's new owner, use or occupant load; 'revision' = a revised certificate. Neither certifies new units: their dwelling units are in units_existing, so min_units counts newly certified units. final · temporary · partial · unknown · change · revision |
certificate_status | enum | Default: issued + expired (both were issued). 'pending' = CO applications not yet issued. issued · expired · pending · void · unknown · all |
renewals | enum | Temporary-certificate RENEWALS (NYC re-issues a TCO every 90 days). Default 'exclude': finals and first-time TCOs only. exclude · include · only default: "exclude" |
issued_after | string | CO date on or after (undated certificates never match) |
issued_before | string | CO date on or before |
min_units | integer | Newly certified dwelling units on or above (units_existing is not counted) |
occupancy_class | string | Building-code occupancy group as published, e.g. R-3, B |
permit_number | string | The building permit the certificate was issued on |
co_number | string | |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
CertificateSearchResponse
| Field | Type | Description |
|---|---|---|
resultsrequired | CertificateSummary[] | |
totalrequired | integer | |
total_capped | boolean | |
total_unknown | boolean | |
pagerequired | integer | |
per_pagerequired | integer | |
sourcesrequired | app__api__certificates__SourceCoverage[] |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/certificates/search"
GET/v1/certificates/{certificate_id}
Get Certificate
One certificate. Unstructured source_record is withheld. A non-canonical id (a duplicate of
another source's row) answers with the canonical one, so a stored id never dead-ends.
Parameters
| Name | Type | Description |
|---|---|---|
certificate_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
CertificateDetail
| Field | Type | Description |
|---|---|---|
idrequired | string | |
co_number | string | |
kindrequired | string | |
co_typerequired | string | |
certificate_statusrequired | string | |
is_renewal | boolean | |
co_date | string | |
co_date_basisrequired | string | |
application_date | string | |
expiration_date | string | |
address_street | string | |
address_city | string | |
address_staterequired | string | |
address_zip | string | |
latitude | number | |
longitude | number | |
parcel_id | string | |
bin | string | |
occupancy_class | string | |
occupancy_description | string | |
use_description | string | |
job_type | string | |
units | integer | |
units_existing | integer | |
square_footage | number | |
stories | integer | |
linked_permit_id | string | |
linked_permit_number | string | |
contractor_name | string | |
contractor_license | string | |
jurisdiction_id | string | |
sourcerequired | string | |
source_idrequired | string | |
originrequired | string | |
co_type_raw | string | |
status_raw | string | |
address_raw | string | |
source_record | object | |
updated_at | string |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/certificates/{certificate_id}"Inspections
Building inspections as cities and counties publish them: inspection type, result (pass, fail, partial, cancelled, scheduled), dates and inspector, linked to the permit we hold where the permit number matches. /v1/inspections/coverage works with any API key, so you can check a place before buying. Inspector comments are not included. Building inspections add-on, $19/mo on Developer or Business; included in Scale.
Start with the dataset coverage, fields and plan access. Authenticate with X-API-Key; enable the dataset in your dashboard.
Make your first request
Identity-free request example and illustrative empty response, not a claim of zero records. Results use InspectionSummary, including result, date_inspected, inspection_date_basis and nullable permit_id. Source coverage is returned separately.
curl
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/inspections/search?city=Los%20Angeles&state=CA&per_page=1"
Python
import os
import requests
response = requests.get(
"https://api.permit-stack.com/v1/inspections/search?city=Los%20Angeles&state=CA&per_page=1",
headers={"X-API-Key": os.environ["PERMITSTACK_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json())Response excerpt
{
"results": [],
"total": null,
"total_unknown": true,
"total_capped": false,
"page": 1,
"per_page": 1,
"sources": []
}GET/v1/inspections/coverage
Inspection Coverage
Which places we hold inspections for, how current and how complete. UNGATED after launch
(any key), so a buyer can check before adding the dataset; before launch it answers the
internal tiers only, like every route here. One row per (source, place). `records` counts
inspection-log rows (summaries excluded); `result_records` those with a PASS / FAIL / PARTIAL
outcome; `linked_records` those linked to a permit we hold. `scope` = permit (inspections of
permitted work) or existing_structure (inspections of existing buildings: search them with
scope=existing).
Parameters
| Name | Type | Description |
|---|---|---|
state | string | 2-letter state code |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/inspections/coverage"
GET/v1/inspections/search
Search Inspections
Search building inspections: type, result and dates as the city publishes them, linked to
the permit we hold where the permit number matches. Newest first (inspection_date, then id);
inspections scheduled for a future date are left out unless upcoming=include|only (or
result=SCHEDULED). Inspector names are not returned. Every response lists the sources it drew
from with their measured `data_through`. Add-on dataset.
Parameters
| Name | Type | Description |
|---|---|---|
permit_id | string | A permit id from /v1/permits |
permit_number | string | The permit number, as the city publishes it or as /v1/permits returns it |
jurisdiction_id | string | A jurisdiction id from /v1/jurisdictions (narrows permit_number) |
city | string | City name (matches the address city or the issuing jurisdiction) |
state | string | 2-letter state code |
zip_code | string | 5-digit ZIP |
address | string | Street address, partial, case-insensitive |
parcel | string | Parcel / APN / folio (formatting ignored) |
date_after | string | inspection_date on or after (undated inspections never match) |
date_before | string | inspection_date on or before |
result | enum | PASS, FAIL, PARTIAL, CANCELLED, SCHEDULED or OTHER PASS · FAIL · PARTIAL · CANCELLED · SCHEDULED · OTHER |
inspection_type | enum | Normalised inspection type, e.g. FRAMING, ROUGH, FINAL PRE_CONSTRUCTION · FOOTING · FOUNDATION · SLAB · UNDERGROUND · ROUGH · FRAMING · SHEATHING · INSULATION · DRYWALL · ROOFING · GAS · SERVICE · FINAL · CO · OTHER |
trade | enum | BUILDING · ELECTRICAL · PLUMBING · MECHANICAL · FIRE · OTHER |
final_only | boolean | Only final / certificate-of-occupancy inspections default: false |
summaries | enum | 'Last inspection' summaries copied from permit records (not inspection logs). Default exclude. exclude · include · only default: "exclude" |
scope | enum | permit (default): inspections of permitted work. existing / occupancy: occupancy inspections of existing buildings that no permit asked for; all. permit · existing · occupancy · all default: "permit" |
upcoming | enum | Future-dated (still scheduled) inspections: exclude (the default, except with result=SCHEDULED), include, or only (soonest first). exclude · include · only |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
InspectionSearchResponse
| Field | Type | Description |
|---|---|---|
resultsrequired | InspectionSummary[] | |
totalrequired | integer | |
total_capped | boolean | |
total_unknown | boolean | |
pagerequired | integer | |
per_pagerequired | integer | |
sourcesrequired | app__api__inspections__SourceCoverage[] |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/inspections/search"
GET/v1/permits/{permit_id}/inspections
Get Permit Inspections
One permit's inspections, newest first (future-dated scheduled ones only with
upcoming=include|only or result=SCHEDULED). 404 when the permit does not exist (the same
answer /v1/permits/{id} gives); an existing permit with no inspection held answers an empty
list, and `sources` is empty -- we hold no inspection feed that names it.
Parameters
| Name | Type | Description |
|---|---|---|
permit_idrequired | string | |
result | enum | PASS · FAIL · PARTIAL · CANCELLED · SCHEDULED · OTHER |
summaries | enum | exclude · include · only default: "exclude" |
upcoming | enum | Future-dated (still scheduled) inspections: exclude (the default, except with result=SCHEDULED), include, or only (soonest first). exclude · include · only |
page | integer | default: 1 |
per_page | integer | default: 100 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
PermitInspectionsResponse
| Field | Type | Description |
|---|---|---|
resultsrequired | InspectionSummary[] | |
totalrequired | integer | |
total_capped | boolean | |
total_unknown | boolean | |
pagerequired | integer | |
per_pagerequired | integer | |
sourcesrequired | app__api__inspections__SourceCoverage[] | |
permit_idrequired | string |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/permits/{permit_id}/inspections"Metrics
Pre-aggregated permit counts and valuation from a nightly rollup. Use these instead of paging through search results to count them: they answer 'how many' and 'is it trending' in one millisecond-scale call. Developer plan and above.
GET/v1/metrics/cities
Metrics Cities
Busiest cities in a state - the ranking customers were building by hand.
Available on the Developer plan and above (see /v1/billing/plans for current pricing).
Parameters
| Name | Type | Description |
|---|---|---|
staterequired | string | |
category | string | |
months | integer | default: 12 |
limit | integer | default: 50 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/metrics/cities"
GET/v1/metrics/current
Metrics Current
Category breakdown over a trailing window - the 'what is happening here now' view.
Available on the Developer plan and above (see /v1/billing/plans for current pricing).
Parameters
| Name | Type | Description |
|---|---|---|
state | string | |
city | string | |
days | integer | Trailing window. Rounded to whole months by the rollup. default: 90 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/metrics/current"
GET/v1/metrics/monthly
Metrics Monthly
Monthly permit counts and total valuation for a city/state/category.
Available on the Developer plan and above (see /v1/billing/plans for current pricing).
Served from a nightly rollup. Inspect `as_of` to assess its age.
At least one of `state` or `city` is required: an
unfiltered national series would be a different (and much larger) product.
Parameters
| Name | Type | Description |
|---|---|---|
state | string | Two-letter state code, e.g. FL |
city | string | City name; case-insensitive |
category | string | Permit category, e.g. ROOFING |
months | integer | How many trailing months to return default: 24 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/metrics/monthly"
Webhooks
Webhooks attempt signed delivery of eligible matching records after ingestion. Most sources have scheduled nightly ingestion; the dispatcher is scheduled every 60 seconds. That cadence is not an arrival deadline. Source publication, matching windows, backlog, retries and endpoint availability affect delivery. Developer plan ($79/mo) and above.
GET/v1/webhooks/
List Webhooks
List all your registered webhooks.
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/webhooks/"
POST/v1/webhooks/
Create Webhook
Register a webhook for eligible matching records after ingestion.
Available on the Developer plan and above (see /v1/billing/plans for current
pricing). Maximum 10 webhooks per API key. Eligible deliveries are JSON POSTs.
Set contractor_name to filter by recorded names. Source coverage and missing
names affect matches; a match does not establish completed work or a customer.
The dispatcher is scheduled every 60 seconds. Matching windows, backlog,
retries and endpoint availability affect delivery; there is no fixed arrival
deadline or guarantee that every matching source record will be delivered.
Check source data-through dates separately from ingestion and dispatch cadence.
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/webhooks/"
DELETE/v1/webhooks/{webhook_id}
Delete Webhook
Delete a webhook.
Parameters
| Name | Type | Description |
|---|---|---|
webhook_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/webhooks/{webhook_id}"PATCH/v1/webhooks/{webhook_id}
Update Webhook
Re-activate (or deactivate) one of your webhooks.
Re-activating resumes delivery from now: permits ingested while the webhook was paused
are not replayed (use /v1/permits/search or /v1/permits/sync to backfill a gap), so a
newly fixed endpoint is not hit with the whole backlog at once. The failure count resets
to zero.
Parameters
| Name | Type | Description |
|---|---|---|
webhook_idrequired | string | |
is_activerequired | boolean | true re-activates a webhook the failure breaker switched off. |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
403 | Your plan does not include this endpoint, or an option you passed. The body is machine-readable: `error` is `feature_locked`, `feature` names the gate, `upgrade_url` links to the cheapest plan that unlocks it, and `current_tier` is the plan you are on. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/webhooks/{webhook_id}"GET/v1/webhooks/{webhook_id}/deliveries
Get Webhook Deliveries
Why your webhook is or is not being delivered, seen from our side of the connection.
Only FAILED attempts are recorded individually; successful deliveries are counted
(fire_count, last_fired_at). An empty `recent_failures` list is therefore good news, not
missing data. `consecutive_failures` is what the automatic pause acts on: when it reaches
the limit the webhook is deactivated, so it is the field to watch.
Parameters
| Name | Type | Description |
|---|---|---|
webhook_idrequired | string | |
limit | integer | How many recent failed attempts to return. default: 20 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/webhooks/{webhook_id}/deliveries"POST/v1/webhooks/{webhook_id}/rotate-secret
Rotate Webhook Secret
Issue a NEW signing secret for this webhook. The old one stops working immediately.
Every delivery after this call is signed with the new secret, so update your verifier
first. Creating a webhook again with the same settings returns the existing secret; this
endpoint is the only way to rotate it.
Parameters
| Name | Type | Description |
|---|---|---|
webhook_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/webhooks/{webhook_id}/rotate-secret"GET/v1/webhooks/{webhook_id}/secret
Get Webhook Secret
Retrieve your webhook signing secret. Use this to validate signatures.
The X-PermitStack-Signature header on incoming webhook requests is the
HMAC-SHA256 of the request body using this secret. Verify before
processing to ensure the request came from PermitStack.
Parameters
| Name | Type | Description |
|---|---|---|
webhook_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/webhooks/{webhook_id}/secret"POST/v1/webhooks/{webhook_id}/test
Test Webhook
Send a test event to a webhook URL.
Useful for verifying your webhook endpoint is reachable and signature
validation works. Sends a fake permit payload with event=permit.test.
Parameters
| Name | Type | Description |
|---|---|---|
webhook_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/webhooks/{webhook_id}/test"Health
Service health checks
GET/health
Health Check
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/health"
GET/stats
Public Stats
Public stats endpoint - no auth required.
Returns aggregate coverage numbers for marketing/transparency.
Cached server-side for 30 minutes.
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/stats"
Code Violations
Code-enforcement violations as cities and counties publish them: case number, violation type and code, category, status, opened and closed dates and, where the source publishes them, fines. Complaints are a separate record kind and are never counted as violations. /v1/violations/coverage works with any API key, so you can check a place before buying; it says which sources keep full history and which keep only a recent window. No owner, complainant or inspector names are included. Code violations add-on, $19/mo on Developer; included in Business and Scale.
Start with the dataset coverage, fields and plan access. Authenticate with X-API-Key; enable the dataset in your dashboard.
GET/v1/violations/coverage
Violation Coverage
Which places we hold code violations for, how current and how complete. UNGATED after
launch (any key), so a buyer can check before adding the dataset; before launch it answers the
internal tiers only, like every route here. One row per (source, place). `records` counts
violations (what a default search returns); `complaint_records` counts complaints, which are
a separate kind; `open_records` violations whose status is OPEN. Counts are in the source's
`count_unit` (rows, or distinct case numbers).
Parameters
| Name | Type | Description |
|---|---|---|
state | string | 2-letter state code |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/violations/coverage"
GET/v1/violations/search
Search Violations
Search code-enforcement violations (and, with record_kind=complaint, complaints) as cities
and counties publish them: type, category, status, dates and, where published, fines. Every
response lists the sources it drew from with their measured `data_through`, their coverage
window (full history, a rolling window, or open cases only) and whether they publish fines.
Add-on dataset: included in Business and Scale, available as an add-on on Developer.
Parameters
| Name | Type | Description |
|---|---|---|
address | string | Street address, partial, case-insensitive |
parcel | string | Parcel / APN / folio / BBL (formatting ignored) |
city | string | City name (matches the address city or the issuing jurisdiction) |
state | string | 2-letter state code |
zip_code | string | 5-digit ZIP |
jurisdiction_id | string | A jurisdiction id from /v1/jurisdictions |
lat | number | |
lng | number | |
radius_miles | number | Radius in miles around lat/lng (default 1) |
date_after | string | record_date on or after (undated records never match) |
date_before | string | record_date on or before |
status | enum | OPEN, CLOSED, COMPLIED, ABATED, CITED, DISMISSED or UNKNOWN OPEN · CLOSED · COMPLIED · ABATED · CITED · DISMISSED · UNKNOWN |
open_only | boolean | Only OPEN records (a citation or judgment is not open) default: false |
category | enum | Normalised category, e.g. HOUSING, UNSAFE, WORK_WITHOUT_PERMIT STRUCTURAL · HOUSING · ZONING · PROPERTY_MAINTENANCE · NUISANCE · UNSAFE · VACANT · FIRE · SIGN · WORK_WITHOUT_PERMIT · ENVIRONMENTAL · OTHER |
record_kind | enum | 'violation' (default): violations, citations and orders the agency found. 'complaint': reports it received, and cases with no evidence a violation was found. 'all': both. Complaints are never counted as violations. violation · complaint · all default: "violation" |
case_number | string | The agency's case / complaint number |
include_uncounted | boolean | Also return records stored but never counted: voided, withdrawn, rescinded or issued in error, and process steps default: false |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
ViolationSearchResponse
| Field | Type | Description |
|---|---|---|
resultsrequired | ViolationSummary[] | |
totalrequired | integer | |
total_capped | boolean | |
total_unknown | boolean | |
pagerequired | integer | |
per_pagerequired | integer | |
sourcesrequired | app__api__violations__SourceCoverage[] |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/violations/search"
GET/v1/violations/{violation_id}
Get Violation
One violation or complaint, with the PII-stripped source fields. A non-canonical id (a twin
source's copy of the same record) answers with the canonical one, so a stored id never
dead-ends.
Parameters
| Name | Type | Description |
|---|---|---|
violation_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
ViolationDetail
| Field | Type | Description |
|---|---|---|
license | string | |
attribution | string | |
license_url | string | |
open_data_url | string | |
idrequired | string | |
record_kindrequired | string | |
case_number | string | |
violation_number | string | |
violation_code | string | |
violation_code_description | string | |
violation_type | string | |
categoryrequired | string | |
statusrequired | string | |
not_counted | enum | void · process |
opened_date | string | |
closed_date | string | |
inspection_date | string | |
record_date | string | |
record_date_basisrequired | string | |
fine_amount | number | |
amount_paid | number | |
balance_due | number | |
address_street | string | |
address_city | string | |
address_staterequired | string | |
address_zip | string | |
latitude | number | |
longitude | number | |
parcel_id | string | |
bin | string | |
permit_id | string | |
linked_permit_number | string | |
jurisdiction_id | string | |
sourcerequired | string | |
source_idrequired | string | |
originrequired | string | |
source_status | string | |
status_raw | string | |
address_raw | string | |
source_record | object | |
twins | TwinRecord[] | |
updated_at | string |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/violations/{violation_id}"Credits
Prepaid record credit packs: list the packs and check an account's balance. Packs are bought on the dashboard; without a plan covering the call, one credit is charged per returned record.
GET/v1/credits/balance
Api Balance
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/credits/balance"
GET/v1/credits/packs
Packs
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/credits/packs"
Development Pipeline
Planning and zoning cases (rezonings, site plans, plats and subdivisions, variances, conditional and special uses, annexations, planned developments, comprehensive-plan amendments, demolition and historic reviews) with status, hearing and decision dates, address and parcel, plus council, planning-commission and zoning-board decisions with the outcome and roll-call votes, linked to the case and to the permits that followed where we can match them. Each case carries a generated scope summary (type, zoning change, units, acres, square feet, uses); no applicant, owner or other free text from the source is included. /v1/pipeline/coverage works with any API key, so you can check a place before buying. Development pipeline add-on, $29/mo on Developer; included in Business and Scale.
Start with the dataset coverage, fields and plan access. Authenticate with X-API-Key; enable the dataset in your dashboard.
GET/v1/pipeline/cases/search
Search Cases
Search planning and zoning cases (rezonings, site plans, plats, variances, conditional /
special uses, annexations, PUDs, comprehensive-plan amendments, demolition and historic
reviews) as cities and counties publish them. Every response lists its sources with their
measured `data_through`. An undated case never matches a date window. Add-on dataset.
Parameters
| Name | Type | Description |
|---|---|---|
city | string | City name (matches the address city or the issuing jurisdiction) |
state | string | 2-letter state code |
zip_code | string | 5-digit ZIP |
jurisdiction_id | string | A jurisdiction id from /v1/jurisdictions |
address | string | Street address, partial, case-insensitive |
parcel | string | Parcel / APN / folio (formatting ignored) |
lat | number | |
lng | number | |
radius_miles | number | Radius in miles around lat/lng (default 1) |
case_type | enum | REZONING, SITE_PLAN, SUBDIVISION_PLAT, VARIANCE, CONDITIONAL_USE, ... REZONING · SITE_PLAN · SUBDIVISION_PLAT · VARIANCE · CONDITIONAL_USE · ANNEXATION · PUD · COMPREHENSIVE_PLAN · DEMOLITION_REVIEW · HISTORIC_REVIEW · OTHER |
status | enum | Normalised case status FILED · UNDER_REVIEW · HEARING_SCHEDULED · APPROVED · APPROVED_WITH_CONDITIONS · DENIED · WITHDRAWN · TABLED · APPEALED · CLOSED · UNKNOWN |
case_number | string | The case number as published (formatting ignored) |
filed_after | string | |
filed_before | string | |
hearing_after | string | Hearing on or after (may be in the future) |
hearing_before | string | |
decided_after | string | |
decided_before | string | |
min_units | integer | Dwelling units proposed, at least (the source's structured unit count) |
min_acres | number | |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
CaseSearchResponse
| Field | Type | Description |
|---|---|---|
resultsrequired | CaseSummary[] | |
totalrequired | integer | |
total_capped | boolean | |
total_unknown | boolean | |
pagerequired | integer | |
per_pagerequired | integer | |
sourcesrequired | app__api__pipeline__SourceCoverage[] |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/pipeline/cases/search"
GET/v1/pipeline/cases/{case_id}
Get Case
One planning case with the meeting decisions linked to it (newest first, up to 100) and
the building permits on the SAME SITE in the case's window (same parcel, or the exact street
address when the case has no usable parcel; filed from the case's filing date to five years
after its decision; up to 100, `permits_total` says how many exist). A linked permit is on the
same site at the right time -- not necessarily issued under this case. Links are computed:
`link_method` / `confidence` say how each was made. A case whose source says its location is
confidential carries no address, parcel or point and no permit links.
Parameters
| Name | Type | Description |
|---|---|---|
case_idrequired | string |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
CaseDetail
| Field | Type | Description |
|---|---|---|
idrequired | string | |
case_number | string | |
case_typerequired | string | |
case_type_raw | string | |
statusrequired | string | |
status_raw | string | |
date_filed | string | |
date_hearing | string | |
date_decision | string | |
record_date | string | |
record_date_basisrequired | string | |
decision_body | string | |
scope_summary | string | Summary built only from the city's structured fields (case type, status, zoning, unit and area counts, designated use fields); no term is taken from free-text descriptions. May be incomplete: an omitted use or count does not mean the source lacks it. |
scope_summary_note | string | Source and limits of scope_summary. |
zoning_from | string | |
zoning_to | string | |
units | integer | |
acres | number | |
square_footage | number | |
address_street | string | |
address_city | string | |
address_staterequired | string | |
address_zip | string | |
parcel_id | string | |
latitude | number | |
longitude | number | |
jurisdiction_id | string | |
sourcerequired | string | |
source_idrequired | string | |
originrequired | string | |
source_url | string | |
decisionsrequired | DecisionDetail[] | |
permitsrequired | LinkedPermit[] | |
permits_totalrequired | integer | |
source_record | object | |
updated_at | string |
Example
curl -H "X-API-Key: pk_your_key_here" \
"https://api.permit-stack.com/v1/pipeline/cases/{case_id}"GET/v1/pipeline/coverage
Pipeline Coverage
Which places we hold planning cases and decisions for, how current and how complete.
UNGATED after launch (any key), so a buyer can check before adding the dataset; before launch
it answers the internal tiers only. One row per (source, place). Decision `records` count
land-use items only (what a default search returns).
Parameters
| Name | Type | Description |
|---|---|---|
state | string | 2-letter state code |
dataset | enum | cases · decisions · all default: "all" |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/pipeline/coverage"
GET/v1/pipeline/decisions/search
Search Decisions
Search council / planning-commission / zoning-board agenda decisions: scope summary, action, pass /
fail and the roll-call tally, with the planning case they concern where we can link it. A
RECOMMENDED_* outcome is a recommending body's, not a final decision. Add-on dataset.
Parameters
| Name | Type | Description |
|---|---|---|
city | string | City name (matches the address city or the deciding jurisdiction) |
state | string | 2-letter state code |
jurisdiction_id | string | |
address | string | Street address named in the item, partial |
body | string | Deciding body, partial ('Planning Commission', 'Zoning') |
outcome | enum | Normalised action: APPROVED, DENIED, RECOMMENDED_APPROVAL, TABLED, ... APPROVED · APPROVED_WITH_CONDITIONS · DENIED · RECOMMENDED_APPROVAL · RECOMMENDED_DENIAL · TABLED · WITHDRAWN · REFERRED · FIRST_READING · RECEIVED · NO_ACTION · OTHER · UNKNOWN |
land_use | enum | 'only' (default): land-use items; 'all': every stored item only · all default: "only" |
land_use_type | enum | REZONING · SITE_PLAN · SUBDIVISION_PLAT · VARIANCE · CONDITIONAL_USE · ANNEXATION · PUD · COMPREHENSIVE_PLAN · DEMOLITION_REVIEW · HISTORIC_REVIEW · OTHER |
case_number | string | A case number named in the item (formatting ignored) |
matter_file | string | The clerk's file number |
linked | boolean | true: only items linked to a planning case we hold |
meeting_after | string | |
meeting_before | string | |
page | integer | default: 1 |
per_page | integer | default: 25 |
Responses
| Code | Meaning |
|---|---|
200 | Successful Response |
401 | Missing or invalid API key. Pass a key as the `X-API-Key` header. |
422 | Validation Error |
429 | Rate limit exceeded -- either the per-minute burst or the daily cap for your plan. Retry after the window resets; the daily cap resets at UTC midnight. |
DecisionSearchResponse
| Field | Type | Description |
|---|---|---|
resultsrequired | DecisionSummary[] | |
totalrequired | integer | |
total_capped | boolean | |
total_unknown | boolean | |
pagerequired | integer | |
per_pagerequired | integer | |
sourcesrequired | app__api__pipeline__SourceCoverage[] |
Example
curl -H "X-API-Key: pk_your_key_here" \ "https://api.permit-stack.com/v1/pipeline/decisions/search"
Prepaid record credit packs
One purchase. Use records as you need them.
- $19 2,000 records
- $49 10,000 records
- $99 25,000 records
One-time purchases expire after 12 calendar months. Oldest credits are spent first. Annual-plan and referral discounts do not apply to packs.
How credits work & what is included
One credit per returned record. A successful data request with no results costs one credit. CSV count and cost previews are free. CSV downloads are capped at the plan export allowance or remaining credits and may be truncated. JSON requests can use one final page beyond the remaining balance; the next purchase first covers that debt. Subscriptions use their plan allowance and never spend credits.
Credits include full-history search features. They exclude contractor phone, email and street address, owner and applicant fields, webhooks, saved-search digests and all dataset add-ons. Those features require an eligible subscription.
For whole-county or multi-state files, request an enterprise export. Contact us to agree scope and delivery. Enterprise export contact