GET /api/v1/context/permits — Permit Requirements

The permits context endpoint returns permit and code-compliance records for home-service trades across U.S. jurisdictions. Each record describes whether a permit is required, what inspections and documents are needed, and any associated fee structure. Records include source links where available. Records backed by deterministic reviewed source data are marked quote_safe: true; records with ambiguous requirements, estimated fees, or unresolved code questions carry quote_safe: false and should be treated as directional context only. Endpoint

GET https://homeservicedata.org/api/v1/context/permits

Query Parameters

string

default:"hvac"

Trade vertical to filter by. One of: hvac, solar, roofing, plumbing, electrical.

string

Two-letter state code (e.g., FL, AZ). Case-insensitive.

string

County name. Partial match, case-insensitive.

string

City name. Partial match against the jurisdiction’s city. Case-insensitive.

boolean

When true, returns only records verified for customer-facing quote use.

integer

default:"100"

Maximum number of records to return. Capped at 500.

Response Fields

array

Array of permit context objects.

Show Record fields

string

Unique record identifier.

object

The authority having jurisdiction (AHJ) for this record.

Show jurisdiction fields

string

Internal jurisdiction authority ID.

string | null

Normalized jurisdiction slug.

string | null

Name of the AHJ (e.g., City of Phoenix Building Department).

string | null

Type: city, county, state, or special_district.

string | null

State code where this jurisdiction operates.

string | null

County name for this jurisdiction.

string | null

5-digit county FIPS code.

string | null

City name for this jurisdiction.

string | null

Jurisdiction’s official website.

string | null

Direct link to the jurisdiction’s permit portal.

string

Trade this permit record applies to.

string | null

Permit type label (e.g., mechanical, electrical, building).

object

Permit and inspection requirement flags.

Show requirements fields

boolean | null

Whether a permit is required for this trade/work type.

boolean | null

Whether a post-installation inspection is required.

boolean | null

Whether a licensed contractor must pull the permit.

boolean | null

Whether contractor registration with the jurisdiction is required.

boolean | null

Whether pre-approval or plan review is required before work begins.

array

List of documents required for permit submission (e.g., equipment_spec_sheet, load_calculation).

array

Conditions that are ambiguous or not yet verified.

object

Permit fee information.

Show fees fields

string | null

Fee structure: flat, valuation_based, tiered, exempt, or unknown.

number | null

Low end of the expected permit fee in USD.

number | null

High end of the expected permit fee in USD.

string | null

Fee calculation formula if the jurisdiction uses a valuation-based or tiered method.

object

Building/energy code context.

Show code fields

string | null

Code basis adopted (e.g., IRC_2021, IECC_2021).

string | null

Code cycle year or label.

string | null

Adoption status: adopted, pending, partial, unknown.

boolean

Whether this record is cleared for use in customer-facing quotes.

string | null

Confidence tier: high, medium, or low.

object

Source traceability.

Show provenance fields

string | null

Internal source document reference.

string | null

URL to the authoritative permit information page.

string | null

ISO 8601 timestamp of last verification.

string

Always permit_code_context.

object

Query summary metadata.

Show Coverage fields

string

Trade filter applied.

string | null

State filter applied.

string | null

County filter applied.

string | null

City filter applied.

integer

Number of records returned.

boolean

Whether results were restricted to quote-safe records.

string

Description of the trust model for this dataset.

Permit requirements and fees change frequently. Always verify current fee schedules directly with the AHJ before including permit costs in a customer contract. Records with quote_safe: false or non-empty unresolved_requirements arrays require manual verification before use in a binding quote.

Filter by quote_safe=true when populating permit fee line items in a proposal. Use quote_safe=false records for internal awareness of jurisdictions that require additional research before closing a job.

Example Request

curl -G https://homeservicedata.org/api/v1/context/permits \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "state=FL" \
  --data-urlencode "city=Orlando" \
  --data-urlencode "quote_safe=true"

Example Response

{
  "success": true,
  "data": {
    "records": [
      {
        "record_id": "pmt_01hzka1bc2de3fg4hi5jk6yzab",
        "jurisdiction": {
          "id": "jur_01hzka1bc2de3fg4hi5abcde",
          "slug": "city-of-orlando-fl",
          "authority_name": "City of Orlando Building Division",
          "jurisdiction_type": "city",
          "state_code": "FL",
          "county_name": "Orange",
          "county_fips": "12095",
          "city_name": "Orlando",
          "website_url": "https://www.orlando.gov/Building",
          "permit_portal_url": "https://permits.orlando.gov"
        },
        "trade": "hvac",
        "permit_type": "mechanical",
        "requirements": {
          "permit_required": true,
          "inspection_required": true,
          "licensed_contractor_required": true,
          "registered_contractor_required": false,
          "preapproval_required": false,
          "required_documents": ["equipment_spec_sheet", "manual_j_summary"],
          "unresolved_requirements": []
        },
        "fees": {
          "amount_type": "flat",
          "fee_low": 85.00,
          "fee_high": 125.00,
          "formula": null
        },
        "code": {
          "basis": "FBC_2023",
          "cycle": "2023",
          "status": "adopted"
        },
        "quote_safe": true,
        "confidence": "high",
        "provenance": {
          "source_document_id": "doc_01hzka1bc2de3fg4hi5jk6orl",
          "source_url": "https://www.orlando.gov/Building/Fees",
          "last_verified_at": "2024-09-10T00:00:00Z",
          "trust_basis": "permit_code_context"
        }
      }
    ],
    "coverage": {
      "trade": "hvac",
      "state": "FL",
      "county": null,
      "city": "Orlando",
      "records_returned": 1,
      "quote_safe_only": true,
      "trust_basis": "Official jurisdiction portals are loaded first; unresolved fee and permit rules return with quote_safe=false."
    }
  }
}

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/context/permits — Permit Requirements

Query Parameters

Response Fields

Example Request

Example Response

​Query Parameters

​Response Fields

​Example Request

​Example Response

Query Parameters

Response Fields

Example Request

Example Response