PlumbIntel API

Quickstart

1. Create a key under Settings → API access (org admins on an API-enabled plan). It’s shown once — store it securely. Pick Live or Test — test keys (pk_test_…) read the same data but are capped at 1,000 req/day for dev & CI.
2. Send it as a bearer token on every request.
3. Read the data envelope back. That’s it.

Request

curl "https://plumbintel.com/api/v1/permits?jurisdiction=phoenix&freshness=hot&limit=2" \
  -H "Authorization: Bearer pk_live_your_key_here"

JavaScript

const res = await fetch(
  "https://plumbintel.com/api/v1/permits?jurisdiction=phoenix&freshness=hot&limit=2",
  { headers: { Authorization: "Bearer pk_live_your_key_here" } },
);
const { data } = await res.json();
console.log(data.permits);

Response (trimmed)

{
  "data": {
    "permits": [
      {
        "id": "fffcf083-c6cf-4b31-a1c9-f4bd32aff87d",
        "permitNumber": "BLD-2026-03608",
        "permitType": "Residential - New Single Family",
        "workClass": "New",
        "status": "Issued",
        "lifecycleStage": "issued",
        "leadFreshness": "hot",
        "leadScore": 0.82,
        "issueDate": "2026-06-22",
        "valuationTotal": 412000,
        "valuationImputed": null,
        "valuationIsImputed": false,
        "address": "1429 E PALM ST",
        "city": "PHOENIX", "state": "AZ", "zip": "85006",
        "apn": "11942003",
        "jurisdiction": "phoenix",
        "contractor": {
          "license": "ROC123456",
          "businessName": "DESERT SKY BUILDERS LLC",
          "classification": "B-01",
          "status": "Active",
          "hasActiveDisciplinary": false
        }
      }
    ],
    "hasMore": true
  },
  "count": 1
}

The permit object

The core resource. Other endpoints reuse these fields; the contractor, parcel, and project objects are documented in the full API reference.

Conventions & rate limits

• Successful responses use the envelope { data, count?, notes? }.
• List endpoints paginate with limit (max 200) + offset, and return hasMore.
• Every response carries X-RateLimit-Limit, -Remaining, -Reset (seconds to UTC midnight), and an X-Request-Id you can quote in support.
• Over your daily cap (10,000 req/day) — or a short per-minute burst — returns 429 with Retry-After.
• Server-to-server only — keys are secrets; don’t embed them in browser or mobile clients.

Errors

Every error returns the same shape with a stable code you can switch on (message text may change):

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  },
  "request_id": "8f1c2e4a-7b3d-4a1e-9c2f-5d6e7a8b9c0d"
}

Endpoint reference

Versioning & changes

• The API is versioned in the path — /api/v1 (current version 1.0.0).
• We add fields and endpoints without notice — parse defensively and ignore unknown fields. We won’t remove or repurpose an existing v1 field.
• Breaking changes ship under a new version (/api/v2); deprecations are announced here and via Deprecation / Sunset response headers with advance notice.

Changelog

• 2026-06-25 — Standard error envelope ({ error: { code, message }, request_id }) + X-Request-Id on every response; offset pagination on the lead, project, and relationship-gap feeds.
• 2026-06-24 — Public v1 launch: permits, contractors, parcels, leads, projects, relationships, exports.