Developer Documentation

Permitlify REST API

Integrate live permit data and AI scores directly into your CRM, workflow, or custom application. All responses are JSON.

Base URL https://permitlify.com/api/v1/ Version v1 Auth API Key Format JSON

Getting Started

Authentication

The Permitlify API uses API key authentication. Pass your key in one of two ways:

Query parameter: append ?api_key=YOUR_KEY to any request
Authorization header: set Authorization: Bearer YOUR_KEY

API access is available on the Agency plan. Use the demo key below to test all endpoints right now — it returns sample data.

DEMO KEY pl_test_k7x2m9n4p8q1r5s3v6w0

Base URL

https://permitlify.com/api/v1/

All endpoints are relative to this base URL. All requests must be made over HTTPS. HTTP requests will be rejected.

Errors

The API uses standard HTTP status codes. Error responses always return a JSON object with error and code fields.

200	OK — Request succeeded.
400	Bad Request — Invalid parameters or malformed JSON body.
401	Unauthorized — Missing or invalid API key.
404	Not Found — The requested resource doesn't exist.

// Example error response
{
  "error": "Invalid or missing API key.",
  "code":  "unauthorized",
  "docs":  "https://permitlify.com/developers/"
}

Rate Limits

Agency plan accounts are limited to 1,000 requests per hour per API key. If you exceed this, you'll receive a 429 Too Many Requests response. The response will include a Retry-After header indicating when you can retry.

Need higher limits? Contact [email protected] for enterprise access.

Endpoints

List permits

GET /api/v1/permits/ Returns a paginated list of permits

Returns all permits accessible to your account. Supports optional filtering by trade, city, score, and tier.

Query Parameters

Parameter	Type	Description
`api_key` required*	string	Your API key (or pass via Authorization header).
`trade` optional	string	Filter by trade. Values: `Roofing`, `HVAC`, `Electrical`, `Plumbing`.
`city` optional	string	Filter by city name, e.g. `Fort Worth`.
`min_score` optional	integer	Only return permits with AI score ≥ this value (0–99).
`tier` optional	string	Filter by tier. Values: `hot`, `warm`, `cool`.

Response

{
  "count": 2,
  "results": [
    {
      "score":   92,
      "tier":    "hot",
      "address": "4821 Ridgemont Dr",
      "number":  "FW-2026-04192",
      "trade":   "Roofing",
      "value":   "$18,500",
      "city":    "Fort Worth",
      "filed":   "Today, 8:14 AM"
    },
    // ...
  ],
  "meta": { "api_version": "v1", "plan": "agency" }
}

Try it now — live request with the demo key:

curl "https://permitlify.com/api/v1/permits/?api_key=pl_test_k7x2m9n4p8q1r5s3v6w0&min_score=70"

Get permit detail

GET /api/v1/permits/{number}/ Returns a single permit by its permit number

Retrieve full details for a specific permit using its unique permit number (e.g. FW-2026-04192).

Path Parameters

Parameter	Type	Description
`number` required	string	The permit number returned from the list endpoint.

curl "https://permitlify.com/api/v1/permits/FW-2026-04192/?api_key=pl_test_k7x2m9n4p8q1r5s3v6w0"

List cities

GET /api/v1/cities/ Returns monitored cities with permit counts

Returns all cities currently monitored by Permitlify, along with today's total permit count for each city.

Response

{
  "count": 5,
  "results": [
    { "name": "Fort Worth", "state": "TX", "permit_count": 13 },
    { "name": "Arlington",  "state": "TX", "permit_count": 8  },
    // ...
  ],
  "meta": { "api_version": "v1" }
}

Score a permit

POST /api/v1/score/ AI-scores a permit from your own data

Submit a permit's key fields and receive an AI-generated lead score (0–100) and tier. Useful for scoring permits you source from your own data pipelines.

Request Body

Field	Type	Description
`trade` required	string	Trade type. E.g. `"Roofing"`, `"HVAC"`, `"Electrical"`, `"Plumbing"`.
`value` required	string \| number	Estimated job value. E.g. `"$18,500"` or `18500`.
`city` optional	string	City name, used for market-level scoring adjustments.

curl -X POST "https://permitlify.com/api/v1/score/?api_key=pl_test_k7x2m9n4p8q1r5s3v6w0" \
  -H "Content-Type: application/json" \
  -d '{"trade": "Roofing", "value": "$18,500", "city": "Fort Worth"}'

Response

{
  "score": 92,
  "tier":  "hot",
  "inputs": {
    "trade": "Roofing",
    "value": "$18,500",
    "city":  "Fort Worth"
  },
  "meta": {
    "api_version": "v1",
    "model": "permitlify-score-v2"
  }
}

Code Examples

Full examples

cURL

# List all hot roofing permits in Fort Worth
curl "https://permitlify.com/api/v1/permits/?api_key=pl_test_k7x2m9n4p8q1r5s3v6w0&trade=Roofing&tier=hot&city=Fort+Worth"

# Score a permit
curl -X POST "https://permitlify.com/api/v1/score/?api_key=pl_test_k7x2m9n4p8q1r5s3v6w0" \
  -H "Content-Type: application/json" \
  -d '{"trade":"HVAC","value":"$9,200","city":"Arlington"}'

Python

import requests

API_KEY = "pl_test_k7x2m9n4p8q1r5s3v6w0"
BASE    = "https://permitlify.com/api/v1"

# Fetch hot permits, score ≥ 80
resp = requests.get(
    f"{BASE}/permits/",
    params={"api_key": API_KEY, "tier": "hot", "min_score": 80}
)
permits = resp.json()["results"]

for p in permits:
    print(f"Score {p['score']} — {p['trade']} at {p['address']}, {p['city']}")

# Score a custom permit
score_resp = requests.post(
    f"{BASE}/score/",
    params={"api_key": API_KEY},
    json={"trade": "Roofing", "value": "$22,000", "city": "Dallas"}
)
print(score_resp.json())

JavaScript (fetch)

const API_KEY = 'pl_test_k7x2m9n4p8q1r5s3v6w0';
const BASE    = 'https://permitlify.com/api/v1';

// List permits with min score 75
const res = await fetch(
  `${BASE}/permits/?api_key=${API_KEY}&min_score=75`
);
const data = await res.json();
console.log(data.results);

// Score a permit
const score = await fetch(`${BASE}/score/?api_key=${API_KEY}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ trade: 'HVAC', value: '$11,500', city: 'Austin' })
});
console.log(await score.json());

Ready to integrate?

API access is included on the Agency plan. Get in touch to unlock your production key.

Request API access