Skip to content
DatasetsBuilding permitsContractor licencesCertificates of occupancyBuilding inspectionsCode violations and complaintsDevelopment pipelineCoverage & freshnessDatasets overview
ProductsAPIWeb searchEnterprise export contactAlerts & webhooksProperty historyAI connector (MCP)
SolutionsInsuranceLenders & CREReal estateRoofingHVACSolarContractors
PricingDocs
ResourcesBlogCompareGlossaryMethodologyStatus
Sign inGet free API key

DEVELOPER RESOURCES

API Reference

Property and construction data: building permits, contractor licences, certificates of occupancy, inspection logs, code violations and complaints, development pipeline. The endpoints below are documented from the OpenAPI snapshot used for this build. Check the generated date and the current public specification when integrating.

Authenticate with an X-API-Key header on every request. Keys are self-serve at permit-stack.com; the free tier needs no card. The machine-readable spec is at /public-openapi.json.

49 endpoints · generated from the specification on 21 November 2026.

Make a requestExplore the REST endpointsConnect an AI appHosted and local MCP setupGet your API keyStart with the free tier

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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
429Rate 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

NameTypeDescription
addressrequiredstring
pageinteger
default: 1
per_pageinteger
default: 25
record_kindstring'permit' (default), a specific record_kind, or 'all'.
default: "permit"

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredPermitSummary[]
hintsHint[]
coverage_confidenceCoverageConfidence
tier_window_daysinteger
tier_window_fromstring
tier_window_clampedboolean
tier_window_upgrade_urlstring
locked_fieldsstring[]
locked_upgrade_urlstring
coverageJurisdictionCoverage[]
total_cappedboolean
total_unknownboolean

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

NameTypeDescription
event_typestringFilter 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)
categorystringPermit category (e.g. solar, battery)
citystringCity name
statestring2-letter state code
jurisdictionstringJurisdiction name (partial)
permit_idstringEvents for a single permit id
detected_afterstringOnly events detected on/after this UTC timestamp (ISO 8601). Inclusive, so a batch sharing one timestamp is re-delivered; prefer `cursor` for polling.
cursorstringOpaque cursor from the previous response's `next_cursor`. Resumes exactly where you stopped, with no duplicates and no gap. Omit on the first call.
pageinteger
default: 1
per_pageinteger
default: 50
limitintegerAlias of `per_page`. Clamped to 100, not rejected.

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredPermitEventOut[]
total_cappedboolean
total_unknownboolean
hintsHint[]
next_cursorstringPass 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

NameTypeDescription
previewbooleanCount 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_costintegerRefuse sizing if its own credit cost changed since balance was read.
expected_rowsintegerRefuse download if the count changed since preview.
expected_credit_costintegerRefuse download if the credit cost changed since preview.
zip_codestring
citystring
statestring
categorystring
statusPermitStatus
property_typePropertyType
tagstring
record_kindstring
default: "permit"
filed_afterstring
filed_beforestring
issued_afterstring
issued_beforestring
date_afterstringOn or after this date, matched against whichever date a record has (issued, else filed).
date_beforestringOn or before this date, matched against whichever date a record has (issued, else filed).
parcelstringParcel number / APN / folio (formatting ignored).
min_valuenumber
max_valuenumber
min_solar_kwnumber
max_solar_kwnumber
min_sqftnumber
has_enrichmentboolean
scopestring
qstring
contractor_namestring
owner_filedbooleantrue 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.
jurisdictionstringA 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.
limitintegerRows 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
keywordstringAlias of `q`.
date_fromstringAlias of `date_after`.
date_tostringAlias of `date_before`.
start_datestringAlias of `date_after`.
end_datestringAlias of `date_before`.

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
403Your 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.
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

NameTypeDescription
zip_codestring5-digit ZIP code
citystringCity name
statestring2-letter state code
jurisdictionstringJurisdiction name (e.g. 'Wake County', 'Tacoma') or partial match
addressstringStreet address, partial + case-insensitive (e.g. '1600 Pennsylvania') - indexed, fast
latnumberLatitude for radius search
lngnumberLongitude for radius search
radius_milesnumberRadius in miles (used with lat/lng)
default: 5.0
fieldsstring'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"
bboxstringMap-viewport bounding box 'minLng,minLat,maxLng,maxLat'. Returns permits whose location falls inside the box (geocoded permits only).
polygonstringA drawn area as a GeoJSON Polygon geometry (URL-encoded), e.g. {"type":"Polygon","coordinates":[[[lng,lat],...]]}. Returns permits inside the polygon (geocoded permits only).
categorystringPermit category (e.g. solar, SOLAR, roofing, hvac - case insensitive)
statusPermitStatusPermit status (e.g. issued, filed, final)
property_typePropertyTypeProperty type (e.g. residential, commercial)
tagstringFilter by tag
record_kindstringRecord 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_afterstringFiled on or after this date
filed_beforestringFiled on or before this date
issued_afterstringIssued on or after this date
issued_beforestringIssued on or before this date
date_afterstringOn 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_beforestringOn or before this date, matched against whichever date a record has (issued, else filed).
parcelstringParcel number / APN / folio (formatting ignored). Returns permits on that parcel where the source publishes one.
min_valuenumberMinimum estimated value
max_valuenumberMaximum estimated value
min_solar_kwnumberMinimum extracted solar system size (kW DC)
max_solar_kwnumberMaximum extracted solar system size (kW DC)
min_sqftnumberMinimum square footage mentioned (from enrichment)
has_enrichmentbooleanOnly permits that have (true) or lack (false) LLM enrichment
scopestringSubstring match on the enriched work scope
qstringCase-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_numberstringExact 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_namestringContractor name (partial match)
owner_filedbooleantrue 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_addressbooleantrue = 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.
pageinteger
default: 1
per_pageintegerResults per page. Above your plan's maximum this is clamped, not rejected; the response echoes the per_page actually applied.
default: 25
keywordstringAlias of `q`.
date_fromstringAlias of `date_after`.
date_tostringAlias of `date_before`.
start_datestringAlias of `date_after`.
end_datestringAlias of `date_before`.
limitintegerAlias of `per_page`. Clamped to your plan's maximum, not rejected.
count_onlybooleanReturn 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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
403Your 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.
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredPermitSummary[]
hintsHint[]
coverage_confidenceCoverageConfidence
tier_window_daysinteger
tier_window_fromstring
tier_window_clampedboolean
tier_window_upgrade_urlstring
locked_fieldsstring[]
locked_upgrade_urlstring
coverageJurisdictionCoverage[]
total_cappedboolean
total_unknownboolean

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
429Rate 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

NameTypeDescription
cursorstringOpaque cursor from the previous response's `next_cursor`. Omit to start the initial full sync from the beginning.
sincestringAlternative start point: an ISO-8601 UTC timestamp; returns permits with updated_at >= since. Ignored when `cursor` is supplied.
limitintegerMax permits per page (cursor page size, up to 50,000).
default: 5000
record_kindstring'permit' (default), a specific record_kind, or 'all'.
default: "permit"
statestringOptional 2-letter state filter to scope the feed.
categorystringOptional category filter (e.g. solar, roofing).
fieldsstring'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

CodeMeaning
200A 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.
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

NameTypeDescription
cursorstringOpaque cursor from the previous response's `next_cursor`.
sincestringISO-8601 UTC timestamp; returns deletions with deleted_at >= since. Ignored when `cursor` is supplied. Omit both to page every recorded deletion.
limitintegerMax 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_kindstringPass 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"
statestringPass 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.
categorystringPass 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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

NameTypeDescription
permit_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
idrequiredstringStable PermitStack id. Pass to GET /v1/permits/{id}."f4be62ed-b522-42a3-907b-b4ab4ec1a102"
permit_numberrequiredstringThe permit number as the issuing jurisdiction publishes it. Not unique across jurisdictions, and not always present."R2608-181"
statusrequiredenumOne 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"
categoryrequiredenumTrade/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"
tagsrequiredstring[]Free-form keywords extracted from the description (e.g. 'pool', 'reroof'). Additive; do not rely on a fixed vocabulary.["pool"]
property_typerequiredstringRESIDENTIAL, 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_streetrequiredstringHeld 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_cityrequiredstringCity 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_staterequiredstring2-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_ziprequiredstring5-digit ZIP where published."32124"
parcel_idstringAssessor 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_rawrequiredstringHeld 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_valuerequirednumberDeclared job value in USD, as published. Frequently null and occasionally nominal -- treat 0 and 1 as 'not stated'.24500.0
date_filedrequiredstringApplication/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_issuedrequiredstringIssue 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_completedrequiredstringCompletion/final date where the source publishes one. Usually null.
approval_daysintegerCalendar days from date_filed to date_issued (null unless both dates present)
construction_daysintegerCalendar days from date_issued to date_completed (null unless both dates present)
contractor_namestringContractor 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_idstringOpaque 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_namestringOwner 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_addressstringProperty-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_namestringThe PermitStack data source this permit came from -- a city, county or statewide feed, which is not always the permit's own city."Daytona Beach"
latitudenumberWGS84 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
longitudenumberWGS84 longitude.-81.0559
location_sourceenumCoordinate 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_precisionenum'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"
enrichmentPermitEnrichmentStructured detail parsed from the description (e.g. solar kW) where we could extract it. Null for most permits.
record_kindstringpermit | 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_expiredrequiredstringExpiry 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_amountnumberPermit/inspection fee where mapped and usable. A null value does not establish that the source never publishes fees or that no fee was charged.
storiesrequiredintegerBuilding stories, where published.1
unitsrequiredintegerDwelling/tenant units, where published.1
square_footagerequirednumberProject square footage, where published. Usually null.2100.0
applicant_namerequiredstringWhoever 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_licensestringContractor'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_atstringWhen 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

FieldTypeDescription
scopestring
work_summarystring
solar_kwnumber
sqftnumber
unitsinteger
is_residentialboolean
is_commercialboolean
materialsstring[]

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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
429Rate 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

NameTypeDescription
statestring2-letter state code
citystringCity name
zip_codestring5-digit ZIP
jurisdictionstringJurisdiction name (partial)
min_age_yearsnumberMinimum age of the PV permit, in years
default: 2
max_age_yearsnumberMaximum age of the PV permit, in years
default: 7
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredPermitSummary[]
hintsHint[]
coverage_confidenceCoverageConfidence
tier_window_daysinteger
tier_window_fromstring
tier_window_clampedboolean
tier_window_upgrade_urlstring
locked_fieldsstring[]
locked_upgrade_urlstring
coverageJurisdictionCoverage[]
total_cappedboolean
total_unknownboolean

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

NameTypeDescription
installerrequiredstringInstaller name to match (contractor/applicant/owner)
statestring2-letter state code
citystringCity name
zip_codestring5-digit ZIP
jurisdictionstringJurisdiction name (partial)
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredPermitSummary[]
hintsHint[]
coverage_confidenceCoverageConfidence
tier_window_daysinteger
tier_window_fromstring
tier_window_clampedboolean
tier_window_upgrade_urlstring
locked_fieldsstring[]
locked_upgrade_urlstring
coverageJurisdictionCoverage[]
total_cappedboolean
total_unknownboolean

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

NameTypeDescription
statestring2-letter state code
citystringCity name
zip_codestring5-digit ZIP
jurisdictionstringJurisdiction name (partial)
min_age_yearsnumberMinimum age of the roofing permit, in years
default: 12
max_age_yearsnumberMaximum age of the roofing permit, in years
default: 25
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredPermitSummary[]
hintsHint[]
coverage_confidenceCoverageConfidence
tier_window_daysinteger
tier_window_fromstring
tier_window_clampedboolean
tier_window_upgrade_urlstring
locked_fieldsstring[]
locked_upgrade_urlstring
coverageJurisdictionCoverage[]
total_cappedboolean
total_unknownboolean

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

NameTypeDescription
traderequiredstringroofing | hvac | mechanical | solar | pool
statestring2-letter state code
citystringCity name
zip_codestring5-digit ZIP
jurisdictionstringJurisdiction name (partial)
min_age_yearsnumberOverride the trade's default minimum age
max_age_yearsnumberOverride the trade's default maximum age
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredPermitSummary[]
hintsHint[]
coverage_confidenceCoverageConfidence
tier_window_daysinteger
tier_window_fromstring
tier_window_clampedboolean
tier_window_upgrade_urlstring
locked_fieldsstring[]
locked_upgrade_urlstring
coverageJurisdictionCoverage[]
total_cappedboolean
total_unknownboolean

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

NameTypeDescription
parcelrequiredstringParcel number / APN / folio. Formatting is ignored - dashes, dots and spaces are stripped before matching.
statestringOptional 2-letter state to disambiguate the same parcel number across counties
pageinteger
default: 1
per_pageinteger
default: 50
limitintegerAlias of per_page.

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
queryrequiredPropertyQuery
foundrequiredboolean
total_matchesrequiredinteger
truncatedrequiredboolean
distinct_addressesinteger
distinct_jurisdictionsinteger
fan_out_warningstring
summaryrequiredPropertySummary
coverageCoverageConfidence
data_currencyJurisdictionCoverage[]
pagerequiredinteger
per_pagerequiredinteger
has_morerequiredboolean
permitsrequiredPermitSummary[]

PropertyQuery

FieldTypeDescription
addressstring
parcelstring
citystring
statestring
zipstring

PropertySummary

FieldTypeDescription
total_permitsrequiredinteger
first_permit_datestring
last_permit_datestring
years_of_historyinteger
total_estimated_valuenumber
categoriesrequiredobject
jurisdictionsrequiredstring[]
contractorsrequiredstring[]
signalsrequiredPropertySignals

PropertySignals

FieldTypeDescription
has_solarboolean
solar_kwnumber
last_solar_datestring
has_batteryboolean
last_battery_datestring
has_roofingboolean
last_roofing_datestring
has_poolboolean
last_pool_datestring
has_additionboolean
has_new_constructionboolean
has_electricalboolean
has_hvacboolean
last_hvac_datestring
has_plumbingboolean
has_demolitionboolean
last_activity_datestring

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

NameTypeDescription
addressrequiredstringStreet address to look up (e.g. '123 Main St')
citystringOptional city to disambiguate identical street addresses
statestringOptional 2-letter state code
zipstringOptional ZIP (prefix-matched)
pageinteger
default: 1
per_pageinteger
default: 50
limitintegerAlias of per_page.

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
queryrequiredPropertyQuery
foundrequiredboolean
total_matchesrequiredinteger
truncatedrequiredboolean
distinct_addressesinteger
distinct_jurisdictionsinteger
fan_out_warningstring
summaryrequiredPropertySummary
coverageCoverageConfidence
data_currencyJurisdictionCoverage[]
pagerequiredinteger
per_pagerequiredinteger
has_morerequiredboolean
permitsrequiredPermitSummary[]

PropertyQuery

FieldTypeDescription
addressstring
parcelstring
citystring
statestring
zipstring

PropertySummary

FieldTypeDescription
total_permitsrequiredinteger
first_permit_datestring
last_permit_datestring
years_of_historyinteger
total_estimated_valuenumber
categoriesrequiredobject
jurisdictionsrequiredstring[]
contractorsrequiredstring[]
signalsrequiredPropertySignals

PropertySignals

FieldTypeDescription
has_solarboolean
solar_kwnumber
last_solar_datestring
has_batteryboolean
last_battery_datestring
has_roofingboolean
last_roofing_datestring
has_poolboolean
last_pool_datestring
has_additionboolean
has_new_constructionboolean
has_electricalboolean
has_hvacboolean
last_hvac_datestring
has_plumbingboolean
has_demolitionboolean
last_activity_datestring

CoverageConfidence

FieldTypeDescription
confidencerequiredstring
coveredrequiredboolean
jurisdictionstring
data_statusstring
data_throughstring
freshnessstring
jurisdiction_permit_countinteger
noterequiredstring
tier_window_daysinteger
tier_window_fromstring
capture_rationumber
capture_checked_atstring
capture_notestring

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

NameTypeDescription
namestringContractor name (partial match)
statestring2-letter state code
citystringCity name
specialtystringSpecialty tag (e.g. solar, roofing, hvac)
license_numberstringExact 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_statestring2-letter state that ISSUED the licence. Not the same as `state`, which is where the contractor pulls permits.
min_permitsintegerMinimum total permits
min_scoreintegerMinimum contractor activity score (0-100)
sortstringSort order: 'score' (default), 'permits', or 'recent'
default: "score"
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
totalrequiredinteger
pagerequiredinteger
per_pagerequiredinteger
resultsrequiredContractorSummary[]
specialties_matchedstring[]

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

NameTypeDescription
contractor_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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

FieldTypeDescription
idrequiredstring
namerequiredstring
license_numberrequiredstring
license_staterequiredstring
cityrequiredstring
staterequiredstring
total_permitsrequiredinteger
first_permit_daterequiredstring
last_permit_daterequiredstring
specialtiesrequiredstring[]
scoreinteger
is_businessboolean
phonerequiredstring
emailrequiredstring
contact_lockedboolean
locked_fieldsstring[]
upgrade_urlstring
withheld_fieldsstring[]
addressrequiredstring
zip_coderequiredstring
recent_categoriesstring[]
avg_project_valuenumber

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

NameTypeDescription
contractor_idrequiredstring
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
402Record credits empty or expired
409Wallet busy, or CSV count/cost changed
422Validation Error
429Rate 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"
    }
  ]
}

Authentication, pagination and response fields

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

NameTypeDescription
contractor_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

FieldTypeDescription
accessrequiredstring
licensesrequiredLicenseRecord[]
totalrequiredinteger
locked_fieldsstring[]
upgrade_urlstring
contractor_idrequiredstring
contractor_namestring
notestring

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

NameTypeDescription
license_numberrequiredstringLicence number as issued (spaces, dashes and case are ignored)
staterequiredstring2-letter issuing state

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

FieldTypeDescription
accessrequiredstring
licensesrequiredLicenseRecord[]
totalrequiredinteger
locked_fieldsstring[]
upgrade_urlstring
license_numberrequiredstring
staterequiredstring
contractorsrequiredLinkedContractor[]

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
}

Authentication, pagination and response fields

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

NameTypeDescription
statestring2-letter state code

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
citystringCity name (matches the address city or the issuing jurisdiction)
statestring2-letter state code
zip_codestring5-digit ZIP
jurisdiction_idstringA jurisdiction id from /v1/jurisdictions
addressstringStreet address, partial, case-insensitive
parcelstringParcel / APN / folio / BBL (formatting ignored)
latnumber
lngnumber
radius_milesnumberRadius in miles around lat/lng (default 1)
kindenum'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_typeenum'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_statusenumDefault: issued + expired (both were issued). 'pending' = CO applications not yet issued.
issued · expired · pending · void · unknown · all
renewalsenumTemporary-certificate RENEWALS (NYC re-issues a TCO every 90 days). Default 'exclude': finals and first-time TCOs only.
exclude · include · only
default: "exclude"
issued_afterstringCO date on or after (undated certificates never match)
issued_beforestringCO date on or before
min_unitsintegerNewly certified dwelling units on or above (units_existing is not counted)
occupancy_classstringBuilding-code occupancy group as published, e.g. R-3, B
permit_numberstringThe building permit the certificate was issued on
co_numberstring
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
resultsrequiredCertificateSummary[]
totalrequiredinteger
total_cappedboolean
total_unknownboolean
pagerequiredinteger
per_pagerequiredinteger
sourcesrequiredapp__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

NameTypeDescription
certificate_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
idrequiredstring
co_numberstring
kindrequiredstring
co_typerequiredstring
certificate_statusrequiredstring
is_renewalboolean
co_datestring
co_date_basisrequiredstring
application_datestring
expiration_datestring
address_streetstring
address_citystring
address_staterequiredstring
address_zipstring
latitudenumber
longitudenumber
parcel_idstring
binstring
occupancy_classstring
occupancy_descriptionstring
use_descriptionstring
job_typestring
unitsinteger
units_existinginteger
square_footagenumber
storiesinteger
linked_permit_idstring
linked_permit_numberstring
contractor_namestring
contractor_licensestring
jurisdiction_idstring
sourcerequiredstring
source_idrequiredstring
originrequiredstring
co_type_rawstring
status_rawstring
address_rawstring
source_recordobject
updated_atstring

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": []
}

Authentication, pagination and response fields

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

NameTypeDescription
statestring2-letter state code

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
permit_idstringA permit id from /v1/permits
permit_numberstringThe permit number, as the city publishes it or as /v1/permits returns it
jurisdiction_idstringA jurisdiction id from /v1/jurisdictions (narrows permit_number)
citystringCity name (matches the address city or the issuing jurisdiction)
statestring2-letter state code
zip_codestring5-digit ZIP
addressstringStreet address, partial, case-insensitive
parcelstringParcel / APN / folio (formatting ignored)
date_afterstringinspection_date on or after (undated inspections never match)
date_beforestringinspection_date on or before
resultenumPASS, FAIL, PARTIAL, CANCELLED, SCHEDULED or OTHER
PASS · FAIL · PARTIAL · CANCELLED · SCHEDULED · OTHER
inspection_typeenumNormalised inspection type, e.g. FRAMING, ROUGH, FINAL
PRE_CONSTRUCTION · FOOTING · FOUNDATION · SLAB · UNDERGROUND · ROUGH · FRAMING · SHEATHING · INSULATION · DRYWALL · ROOFING · GAS · SERVICE · FINAL · CO · OTHER
tradeenum
BUILDING · ELECTRICAL · PLUMBING · MECHANICAL · FIRE · OTHER
final_onlybooleanOnly final / certificate-of-occupancy inspections
default: false
summariesenum'Last inspection' summaries copied from permit records (not inspection logs). Default exclude.
exclude · include · only
default: "exclude"
scopeenumpermit (default): inspections of permitted work. existing / occupancy: occupancy inspections of existing buildings that no permit asked for; all.
permit · existing · occupancy · all
default: "permit"
upcomingenumFuture-dated (still scheduled) inspections: exclude (the default, except with result=SCHEDULED), include, or only (soonest first).
exclude · include · only
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
resultsrequiredInspectionSummary[]
totalrequiredinteger
total_cappedboolean
total_unknownboolean
pagerequiredinteger
per_pagerequiredinteger
sourcesrequiredapp__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

NameTypeDescription
permit_idrequiredstring
resultenum
PASS · FAIL · PARTIAL · CANCELLED · SCHEDULED · OTHER
summariesenum
exclude · include · only
default: "exclude"
upcomingenumFuture-dated (still scheduled) inspections: exclude (the default, except with result=SCHEDULED), include, or only (soonest first).
exclude · include · only
pageinteger
default: 1
per_pageinteger
default: 100

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
resultsrequiredInspectionSummary[]
totalrequiredinteger
total_cappedboolean
total_unknownboolean
pagerequiredinteger
per_pagerequiredinteger
sourcesrequiredapp__api__inspections__SourceCoverage[]
permit_idrequiredstring

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

NameTypeDescription
staterequiredstring
categorystring
monthsinteger
default: 12
limitinteger
default: 50

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

NameTypeDescription
statestring
citystring
daysintegerTrailing window. Rounded to whole months by the rollup.
default: 90

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

NameTypeDescription
statestringTwo-letter state code, e.g. FL
citystringCity name; case-insensitive
categorystringPermit category, e.g. ROOFING
monthsintegerHow many trailing months to return
default: 24

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
429Rate 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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

NameTypeDescription
webhook_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
webhook_idrequiredstring
is_activerequiredbooleantrue re-activates a webhook the failure breaker switched off.

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
403Your 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.
422Validation Error
429Rate 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

NameTypeDescription
webhook_idrequiredstring
limitintegerHow many recent failed attempts to return.
default: 20

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
webhook_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
webhook_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
webhook_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

CodeMeaning
200Successful 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

CodeMeaning
200Successful 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

NameTypeDescription
statestring2-letter state code

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
addressstringStreet address, partial, case-insensitive
parcelstringParcel / APN / folio / BBL (formatting ignored)
citystringCity name (matches the address city or the issuing jurisdiction)
statestring2-letter state code
zip_codestring5-digit ZIP
jurisdiction_idstringA jurisdiction id from /v1/jurisdictions
latnumber
lngnumber
radius_milesnumberRadius in miles around lat/lng (default 1)
date_afterstringrecord_date on or after (undated records never match)
date_beforestringrecord_date on or before
statusenumOPEN, CLOSED, COMPLIED, ABATED, CITED, DISMISSED or UNKNOWN
OPEN · CLOSED · COMPLIED · ABATED · CITED · DISMISSED · UNKNOWN
open_onlybooleanOnly OPEN records (a citation or judgment is not open)
default: false
categoryenumNormalised category, e.g. HOUSING, UNSAFE, WORK_WITHOUT_PERMIT
STRUCTURAL · HOUSING · ZONING · PROPERTY_MAINTENANCE · NUISANCE · UNSAFE · VACANT · FIRE · SIGN · WORK_WITHOUT_PERMIT · ENVIRONMENTAL · OTHER
record_kindenum'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_numberstringThe agency's case / complaint number
include_uncountedbooleanAlso return records stored but never counted: voided, withdrawn, rescinded or issued in error, and process steps
default: false
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
resultsrequiredViolationSummary[]
totalrequiredinteger
total_cappedboolean
total_unknownboolean
pagerequiredinteger
per_pagerequiredinteger
sourcesrequiredapp__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

NameTypeDescription
violation_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
licensestring
attributionstring
license_urlstring
open_data_urlstring
idrequiredstring
record_kindrequiredstring
case_numberstring
violation_numberstring
violation_codestring
violation_code_descriptionstring
violation_typestring
categoryrequiredstring
statusrequiredstring
not_countedenum
void · process
opened_datestring
closed_datestring
inspection_datestring
record_datestring
record_date_basisrequiredstring
fine_amountnumber
amount_paidnumber
balance_duenumber
address_streetstring
address_citystring
address_staterequiredstring
address_zipstring
latitudenumber
longitudenumber
parcel_idstring
binstring
permit_idstring
linked_permit_numberstring
jurisdiction_idstring
sourcerequiredstring
source_idrequiredstring
originrequiredstring
source_statusstring
status_rawstring
address_rawstring
source_recordobject
twinsTwinRecord[]
updated_atstring

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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
429Rate 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

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
429Rate 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

NameTypeDescription
citystringCity name (matches the address city or the issuing jurisdiction)
statestring2-letter state code
zip_codestring5-digit ZIP
jurisdiction_idstringA jurisdiction id from /v1/jurisdictions
addressstringStreet address, partial, case-insensitive
parcelstringParcel / APN / folio (formatting ignored)
latnumber
lngnumber
radius_milesnumberRadius in miles around lat/lng (default 1)
case_typeenumREZONING, SITE_PLAN, SUBDIVISION_PLAT, VARIANCE, CONDITIONAL_USE, ...
REZONING · SITE_PLAN · SUBDIVISION_PLAT · VARIANCE · CONDITIONAL_USE · ANNEXATION · PUD · COMPREHENSIVE_PLAN · DEMOLITION_REVIEW · HISTORIC_REVIEW · OTHER
statusenumNormalised case status
FILED · UNDER_REVIEW · HEARING_SCHEDULED · APPROVED · APPROVED_WITH_CONDITIONS · DENIED · WITHDRAWN · TABLED · APPEALED · CLOSED · UNKNOWN
case_numberstringThe case number as published (formatting ignored)
filed_afterstring
filed_beforestring
hearing_afterstringHearing on or after (may be in the future)
hearing_beforestring
decided_afterstring
decided_beforestring
min_unitsintegerDwelling units proposed, at least (the source's structured unit count)
min_acresnumber
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
resultsrequiredCaseSummary[]
totalrequiredinteger
total_cappedboolean
total_unknownboolean
pagerequiredinteger
per_pagerequiredinteger
sourcesrequiredapp__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

NameTypeDescription
case_idrequiredstring

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
idrequiredstring
case_numberstring
case_typerequiredstring
case_type_rawstring
statusrequiredstring
status_rawstring
date_filedstring
date_hearingstring
date_decisionstring
record_datestring
record_date_basisrequiredstring
decision_bodystring
scope_summarystringSummary 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_notestringSource and limits of scope_summary.
zoning_fromstring
zoning_tostring
unitsinteger
acresnumber
square_footagenumber
address_streetstring
address_citystring
address_staterequiredstring
address_zipstring
parcel_idstring
latitudenumber
longitudenumber
jurisdiction_idstring
sourcerequiredstring
source_idrequiredstring
originrequiredstring
source_urlstring
decisionsrequiredDecisionDetail[]
permitsrequiredLinkedPermit[]
permits_totalrequiredinteger
source_recordobject
updated_atstring

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

NameTypeDescription
statestring2-letter state code
datasetenum
cases · decisions · all
default: "all"

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

NameTypeDescription
citystringCity name (matches the address city or the deciding jurisdiction)
statestring2-letter state code
jurisdiction_idstring
addressstringStreet address named in the item, partial
bodystringDeciding body, partial ('Planning Commission', 'Zoning')
outcomeenumNormalised 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_useenum'only' (default): land-use items; 'all': every stored item
only · all
default: "only"
land_use_typeenum
REZONING · SITE_PLAN · SUBDIVISION_PLAT · VARIANCE · CONDITIONAL_USE · ANNEXATION · PUD · COMPREHENSIVE_PLAN · DEMOLITION_REVIEW · HISTORIC_REVIEW · OTHER
case_numberstringA case number named in the item (formatting ignored)
matter_filestringThe clerk's file number
linkedbooleantrue: only items linked to a planning case we hold
meeting_afterstring
meeting_beforestring
pageinteger
default: 1
per_pageinteger
default: 25

Responses

CodeMeaning
200Successful Response
401Missing or invalid API key. Pass a key as the `X-API-Key` header.
422Validation Error
429Rate 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

FieldTypeDescription
resultsrequiredDecisionSummary[]
totalrequiredinteger
total_cappedboolean
total_unknownboolean
pagerequiredinteger
per_pagerequiredinteger
sourcesrequiredapp__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