API reference

OpenPermits API

Paths and parameters follow the Shovels v2 API, so existing clients can switch by changing the base URL and key. Create a key under API keys and send it in the X-API-Key header from your servers. Money is in cents; dates are YYYY-MM-DD.

curl https://api.openpermits.ai/v2/permits/search \
  -H "X-API-Key: $OPENPERMITS_KEY" \
  -G -d geo_id=ga/atlanta -d permit_tags=SOLAR,-POOL_AND_HOT_TUB \
  -d permit_from=2026-01-01 -d permit_to=2026-12-31 -d size=100

Pages return next_cursor; pass it back as cursor for the next page. To keep a copy in sync, page through once, then ask only for what changed with updated_since (or first_seen_since for new permits only). For new permits without gaps, stop each poll at settled_through from /v2/meta/release (pass it as first_seen_before) and start the next one there: permits before it are fully geocoded and linked. The full machine-readable spec is at /v2/openapi.json.

Credits and limits

Data endpoints cost one credit per record returned, and one per single-record lookup. Empty results, include_count and the reference endpoints are free. Every charged response reports your allowance:

X-Credits-Charged: 100
X-Credits-Used: 12400
X-Credits-Limit: 50000
X-Credits-Remaining: 37600
X-Credits-Reset: 2026-10-25

Errors

Errors are JSON with a detail, a stable code where you might branch on it, and a request_id to quote to support.

Webhooks

Turn on webhooks for a saved search and add an endpoint under Settings → Webhooks. After each data refresh we POSTthe search's new permits to every endpoint that's on, up to 100 per event, in the same shape as /v2/permits/search. Each permit costs one credit. Reply with any 2xx within 10 seconds; anything else is retried with backoff for about a day, and redirects aren't followed. The same event can arrive twice, so use id to ignore repeats.

POST /your/endpoint
OP-Event-Id: evt_…
OP-Event-Type: permits.new
OP-Signature: t=1790000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "id": "evt_…",
  "type": "permits.new",
  "created": "2026-09-25T13:15:04.120Z",
  "saved_search": { "id": "…", "name": "Roofing in 30306", "url": "https://openpermits.ai/search?…" },
  "window": { "first_seen_since": "2026-09-25T06:02:11.000Z", "first_seen_before": "2026-09-25T12:03:40.000Z" },
  "page": 0,
  "permits": [ { "id": "…", "number": "BLD2026-01234", "tags": ["ROOFING"], … } ]
}

Check the signature before trusting a request: HMAC-SHA256 of `${t}.${raw body}`with your endpoint's signing secret must equal v1, and t should be within five minutes of now.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(header, rawBody, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Permits

Contractors

Properties

Addresses

Decisions

Zoning and land-use agenda items from city and county bodies.

Markets

Monthly permit activity and contractor market share for a geography, recomputed after every data refresh.

Signals

Ready-made lead and risk lists built from permit history.

Reference

Account