Permits (listing endpoint)

curl --request GET \
  --url https://api.permitcore.io/v1/permits

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.permitcore.io/v1/permits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.permitcore.io/v1/permits"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.permitcore.io/v1/permits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

GET

permits

Permits (listing endpoint)

curl --request GET \
  --url https://api.permitcore.io/v1/permits

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.permitcore.io/v1/permits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.permitcore.io/v1/permits"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.permitcore.io/v1/permits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

Returns paginated permit rows filtered by jurisdiction + date range. The response example below is generated from the live OpenAPI spec at api.permitcore.io/openapi.json — re-pulled before each docs deploy, never hand-written.

Authentication

Authorization: Bearer <your-api-key> — see Authentication.

Query parameters

These are the parameters /v1/permits actually accepts, per the live OpenAPI spec. There is no cohort parameter on /v1/permits — buyer-segment filtering lives on the /v1/permits/target variant via target_segment.

Param	Type	Notes
`jurisdiction`	string (slug)	Comma-separated jurisdiction slug(s), e.g. `nyc`, `la`.
`issued_after`	ISO 8601 date	Lower bound for `issued_date` (YYYY-MM-DD).
`issued_before`	ISO 8601 date	Upper bound for `issued_date`.
`permit_type`	string	Filter by normalized permit type.
`work_class`	string	Filter by work class.
`bbox`	string	`minLon,minLat,maxLon,maxLat` bounding box.
`min_valuation`	integer	Minimum `valuation_usd`.
`has_extracted`	boolean	Only rows with LLM-extracted enrichment.
`updated_since`	ISO 8601 date-time	Rows changed since a timestamp (delta sync).
`contractor_canonical_id`	integer	Filter to one canonical contractor.
`parcel_key`	string	Filter to one parcel.
`q`	string	Free-text search (contractor / owner). Min 3 chars.
`order_by`	enum	`issued_date` (default) · `applied_date` · `last_seen_at` · `valuation_usd`.
`order_dir`	enum	`asc` · `desc`.
`page`	integer	1-indexed page number (offset pagination).
`per_page`	integer	Page size; 1–500.
`cursor`	string	Opaque keyset cursor for deep paging — see Pagination. When supplied, `page` is ignored.

Response shape

The example below is generated from the PermitResponse schema in openapi.json. The enrichment fields (cohort, dq_flags, top-level PLUTO-derived fields, description_llm_enriched) are now on the wire as of the 2026-06-04 promotion. The nested pluto DQ-status object is list-endpoint NULL by design — see the list-vs-detail asymmetry note below.

{
  "items": [
    {
      "id": 4218034,
      "jurisdiction_slug": "nyc",
      "source_permit_id": "BT-202601090",
      "canonical_uid": "1:BT-202601090",
      "filing_id": null,

      "address_full": "82 ASP 1ST FLOOR, Manhattan, NY 10009",
      "address_street": "82 ASP",
      "address_city": "Manhattan",
      "address_state": "NY",
      "address_zip": "10009",
      "parcel_apn": "1004920019",
      "lat": 40.7271,
      "lng": -73.9836,
      "geocode_confidence": 0.92,
      "geocode_source": "city_geocoder_v2",

      "permit_type_raw": "BUILDING/EW",
      "permit_type_normalized": "alteration",
      "work_class": "alteration_minor",
      "building_subtype": "tenant_improvement",
      "is_new_construction": false,
      "is_alteration": true,
      "is_demolition": false,

      "units_residential": null,
      "units_commercial": null,
      "units_total": null,
      "square_footage_total": null,
      "valuation_usd": 18400,

      "year_built": 1925,
      "building_class": "O4",
      "zoning_district": "C6-2",
      "lot_area": 2540,

      "applied_date": "2026-05-20",
      "issued_date": "2026-05-27",
      "finaled_date": null,
      "expired_date": null,

      "current_status": "issued",
      "status_raw": "ISSUED-PARTIAL",
      "description_raw": "Interior reno @ unit 3R; partition + finishes; no MEP scope",
      "description_extracted": null,
      "description_llm_enriched": null,

      "applicant_name": null,
      "applicant_role": null,
      "contractor_name": "MIDTOWN BUILD CO INC",
      "contractor_license": "GC-0148921",
      "architect_name": null,
      "engineer_name": null,
      "owner_name": null,

      "source_url": "https://www.nyc.gov/site/buildings/permit/BT-202601090",
      "first_seen_at": "2026-05-27T03:14:22Z",
      "last_seen_at": "2026-06-04T03:11:08Z",
      "last_changed_at": "2026-05-27T03:14:22Z",

      "cohort": "commercial_alteration",
      "dq_flags": {
        "issued_date_is_parse_bug": false,
        "issued_date_is_placeholder": false,
        "issued_date_is_future_dated": false,
        "valuation_usd_is_placeholder": false,
        "valuation_usd_is_oob": false,
        "units_residential_is_placeholder": false,
        "units_total_is_placeholder": false,
        "units_residential_is_oob": false,
        "units_total_is_oob": false,
        "units_commercial_is_placeholder": false,
        "geocode_is_sentinel": false,
        "geocode_is_oob": false
      },
      "pluto": null
    }
  ],
  "pagination": {
    "total_count": 1000,
    "next_page": 2,
    "has_more": true
  }
}

The pagination object above is abbreviated for readability. See Pagination for the full, canonical envelope both this endpoint and /v1/permits/target return.

Pagination

/v1/permits and /v1/permits/target return the same response envelope:

{
  "items": [ /* … */ ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_pages": 40,
    "total_count": 1000,
    "total_count_is_estimate": true,
    "has_more": true,
    "next_page": 2,
    "prev_page": null,
    "next_cursor": "eyJpc3N1ZWRfZGF0ZSI6…"
  },
  "filters_applied": { "jurisdiction": "nyc" },
  "query_time_ms": 34
}

total_count is capped at 1,000 on selective-filter queries, and jurisdiction-only queries use a fast row estimate. When total_count_is_estimate or has_more is true, the true total exceeds total_count — render it as "1,000+" if you surface it directly.
Offset paging (both endpoints): pass page + per_page.
Keyset / cursor paging (/v1/permits only): pass the prior response’s pagination.next_cursor back as the cursor query parameter to page deep or across jurisdictions without an OFFSET scan. When cursor is supplied, page is ignored; the cursor is bound to the request’s order_by/order_dir, so keep those stable while paging. next_cursor is null on the last page. /v1/permits/target is offset-only (page/per_page).

What’s on the wire

The list-endpoint shape carries 58 fields organized as:

Identity — id, jurisdiction_slug, source_permit_id, canonical_uid, filing_id
Address — address_full, address_street, address_city, address_state, address_zip, parcel_apn
Geocode metadata — lat, lng, geocode_confidence, geocode_source
Type + classification — permit_type_raw, permit_type_normalized, work_class, building_subtype, is_new_construction, is_alteration, is_demolition
Scope — units_residential, units_commercial, units_total, square_footage_total, valuation_usd
PLUTO-derived (denormalized) — year_built, building_class, zoning_district, lot_area
Dates — applied_date, issued_date, finaled_date, expired_date
Status + description — current_status, status_raw, description_raw, description_extracted, description_llm_enriched
People — applicant_name, applicant_role, contractor_name, contractor_license, architect_name, engineer_name, owner_name
Source link + timestamps — source_url, first_seen_at, last_seen_at, last_changed_at
Enrichment — cohort, dq_flags, pluto

Most fields are nullable — coverage varies by jurisdiction and by upstream record completeness.

Enrichment field semantics

cohort — the buyer-targeting bucket the row classifies into, one of the 23 canonical segments. null = row not in the cohort matview OR in the matview but unsegmented. Identical taxonomy to target_segment on /v1/permits/target. See Concepts → Cohorts.
dq_flags — 12-key boolean object from the bounds-rule registry. All 12 keys are always present when this field is non-null. Semantic note: false means “the rule has not flagged this value,” NOT “the value was independently verified clean.” NULL silver flag values are coerced to false per the SD-039 rule. See Data freshness → field-level DQ flags for the full flag set + semantics.
description_llm_enriched — LLM-extracted feature object (e.g. scope_summary, unit_count, square_footage, tenant_improvement_flag). Distinct column from description_extracted (which is adapter-populated, per-jurisdiction shape). Coverage today: Austin + Chicago commercial_new permits only (~17,861 prod rows). Broader cross-metro LLM extraction is on the roadmap.

List-vs-detail asymmetry: the nested `pluto` object

The nested pluto object (PLUTO parcel-data presence + per-flag DQ status — {is_placeholder, oob}) is ALWAYS null on /v1/permits by design. The PLUTO LEFT JOIN required to populate the DQ-status object would add ~75ms p95 to the list query, which disqualifies it for the browse path. To get the populated pluto object, query the per-permit detail endpoint:

GET /v1/permits/by-canonical-uid/{canonical_uid}

See Get a permit by canonical_uid. Note that the top-level PLUTO-derived fields (year_built, building_class, zoning_district, lot_area, units_total) are denormalized into the silver layer and DO populate on this endpoint when known. Only the nested pluto DQ-status object is detail-only.

The `/v1/permits/target` variant

/v1/permits/target returns the same response envelope but exposes a curated commercial/multifamily/ADU slice, filtered by target_segment=<segment>. This is the cohort-classified slice that the site’s recency surfaces query. It also adds geo filters (state, metro_cbsa), value bounds (value_min/value_max), and enrichment filters (climate_zone, roof_area_min, hvac_tonnage_min). It is offset-only (no cursor). target_segment accepts a comma-separated list of the 23 canonical segment slugs (see Cohorts). Behavior:

Valid segment with zero rows in window: 200 OK with an empty items array — no 404. Use pagination.total_count to confirm the empty result.
Invalid slug (not in the 23-segment enum): 422 Unprocessable Entity (invalid-target-segment) with a problem+json body enumerating the accepted whitelist.
Newer cohort caveat: multifamily_mep is filterable and populated but not yet certified to the ≥99% precision bar of the other 22 segments — currently 3 metros (primarily Austin), largely historical. See the note on Cohorts. The other 22 are the established, certified set.

/v1/permits/target also has a separate cohort parameter — but it is a per-manufacturer cohort (an A5 YAML basename such as roofing-manufacturer), not a buyer segment. An unknown value returns 400 (unknown-cohort). Use target_segment for segment filtering; use cohort only for manufacturer-cohort targeting.

Quotas

Quotas are tier-based and apply to every request against this endpoint. See Rate limits for the matrix + the X-RateLimit-* response headers + the 429 problem+json shape.

Example request

curl "https://api.permitcore.io/v1/permits?jurisdiction=nyc&issued_after=2026-05-01&per_page=25" \
  -H "Authorization: Bearer $PERMITCORE_API_KEY" \
  -H "Accept: application/json"

Get a permit by canonical_uid — the per-permit detail endpoint with full enrichment + nested pluto.
Cohort distribution — aggregate counts behind these rows.
Free sandbox — client-side DuckDB-WASM queries against the last 10 days of permits across the live metros. No signup, no API key.

Introduction

Concepts

API Reference

Reference

Permits (listing endpoint)

Authentication

Query parameters

Response shape

What’s on the wire

Enrichment field semantics

List-vs-detail asymmetry: the nested `pluto` object

The `/v1/permits/target` variant

Quotas

Example request

​Authentication

​Query parameters

​Response shape

​Pagination

​What’s on the wire

​Enrichment field semantics

​List-vs-detail asymmetry: the nested pluto object

​The /v1/permits/target variant

​Quotas

​Example request

​Related

Authentication

Query parameters

Response shape

Pagination

What’s on the wire

Enrichment field semantics

List-vs-detail asymmetry: the nested `pluto` object

The `/v1/permits/target` variant

Quotas

Example request

Related