Kukun API

Permits API Quickstart

The Kukun Permits API provides full-text and filtered search across 650M+ U.S. residential and commercial building permits. Records are normalized into the Kukun taxonomy, enriched with sub-permit activity, and refreshed daily.

Our APIs are designed for teams building products and workflows in:

Real Estate
PropTech
Construction Intelligence
Home Improvement
Insurance & Risk
Lending & Underwriting

Key Features

The API provides access to multiple core resources and services, including:

Permits

650M+ U.S. residential and commercial permits, normalized into the Kukun taxonomy and enriched with sub-permit signals. Surfaces approximately 40% more activity than raw municipal feeds — kitchen remodels filed as plumbing or electrical, additions buried inside structural permits, and similar hidden activity.

Features include:

Full-text search across permit fields
Filtering by status, label, address, city, state, ZIP, county, jurisdiction
Geo-distance search by latitude, longitude, and radius
Sorting and pagination
Historical permit activity, refreshed daily

Property Data (Coming soon)

Property records with assessor and parcel-level metadata. Currently available via Kukun’s data delivery team — REST endpoints are planned for a future release. Contact [email protected] to discuss access today.

Features include:

Property enrichment
Address-based queries
Structured property records
Geographic segmentation

Getting Started

API access is enterprise-only today. To request a key, email [email protected] with:

Your company and use case
Expected monthly request volume
Target environment (sandbox, production, or both)

Standard turnaround is two business days. Production keys are issued after a brief security review. Once your key is active, see the API Reference section for available endpoints.

Authentication

All API requests require authentication. Pass your API key as a Bearer token in the Authorization header on every request.

Example request:

Code
curl -X GET "https://api.mykukun.com/v1/permits/search" \
  -H "Authorization: Bearer YOUR_API_KEY"

Base URL

All API endpoints are served under the following base URLs:

Code
https://api.mykukun.com/v1

Response Format

All API responses are JSON, with Content-Type: application/json.

Example paginated response:


Code
{
  "success": true,
  "message": {
    "permits": [
      {
        "permit": {
          "id": "CAEO000112393",
          "number": "#APP2026-00030",
          "description": "Applicant made small revision to grading and drainage on lot site work. no changes to building landscape etc",
          "status": "applied",
          "labels": "new_construct",
          "ailabels": ["new_construct"],
          "aibuiling_category": "commercial",
          "city_assigned_cost": null,
          "fees": null,
          "inspection_pass_rate": null,
          "timeline": [
            {
              "status": "applied",
              "date": "2026-02-04"
            }
          ],
          "durations": {
            "total_days": 0,
            "construction_days": null,
            "approval_days": null
          }
        },
        "location": {
          "address": {
            "street_address": null,
            "city": "North Fair Oaks",
            "county": "San Mateo",
            "state": "California",
            "zip_code": "94025",
            "zip_plus4": "1840"
          },
          "coordinates": {
            "lat": 37.47305,
            "lng": -122.20266
          },
          "postal_metadata": {
            "delivery_point_barcode": "940251840"
          },
          "jurisdiction": "North Fair Oaks"
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  },
  "errors": null,
  "metadata": {
    "responseId": "response-id",
    "timestamp": "2026-05-20T00:00:00.000Z",
    "version": "v1"
  }
}

When page equals totalPages, there are no additional pages to request.

Pagination

The Kukun API uses page-based pagination. Request a specific page using the page query parameter; control page size with limit (max 1000).

Example:

Code
GET /v1/permits/search?size=10

Code
GET /v1/permits/search...

HTTP Response Codes

The API uses standard HTTP status codes.

Code	Description
200	Success
400	Bad request — malformed syntax or invalid parameter
401	Unauthorized — missing or invalid API key
403	Forbidden — your key does not have access to this resource
404	Not found — the requested resource does not exist
422	Unprocessable entity — request body or parameters failed validation
429	Too many requests — see the Retry-After header
500	Internal server error — contact support if persistent

Error Handling

Validation and request errors return structured JSON responses with a consistent shape:

Example:


Code
{ 
  "error": { "code": "validation_error",
             "message": "The `status` parameter must be one of: applied, issued, in-process, denied, closed, review, expired, inspection.",
             "param": "status"
            }
}

API Versioning

The current API version is:

Code
v1

Versioning is included directly in the request path:

Code
/v1/permits/search

Future API versions may introduce additional capabilities while maintaining backward compatibility whenever possible.

API Reference

The API Reference section documents every endpoint with parameters, authentication, request and response examples, and error responses.

Continue to API Reference section to explore all available endpoints.

Best Practices

To improve performance and result quality:

Filter by date range and geography before broader filters — these are indexed first
Use the smallest limit that meets your needs; the maximum is 1000 per request
For bulk pulls of more than 100K records, contact [email protected] about flat-file delivery
Cache static responses (jurisdiction lists, label taxonomy) — these change infrequently
Respect the Retry-After header on 429 responses

Support

Email [email protected] for authentication, rate-limit, or data-availability issues. Standard response time is one business day. For sales questions, use [email protected].

Last modified on May 21, 2026

Introduction

Kukun API

Permits API Quickstart

Our APIs are designed for teams building products and workflows in:

Real Estate
PropTech
Construction Intelligence
Home Improvement
Insurance & Risk
Lending & Underwriting

Key Features

The API provides access to multiple core resources and services, including:

Permits

Features include:

Full-text search across permit fields
Filtering by status, label, address, city, state, ZIP, county, jurisdiction
Geo-distance search by latitude, longitude, and radius
Sorting and pagination
Historical permit activity, refreshed daily

Property Data (Coming soon)

Features include:

Property enrichment
Address-based queries
Structured property records
Geographic segmentation

Getting Started

API access is enterprise-only today. To request a key, email [email protected] with:

Your company and use case
Expected monthly request volume
Target environment (sandbox, production, or both)

Standard turnaround is two business days. Production keys are issued after a brief security review. Once your key is active, see the API Reference section for available endpoints.

Authentication

All API requests require authentication. Pass your API key as a Bearer token in the Authorization header on every request.

Example request:

Code
curl -X GET "https://api.mykukun.com/v1/permits/search" \
  -H "Authorization: Bearer YOUR_API_KEY"

Base URL

All API endpoints are served under the following base URLs:

Code
https://api.mykukun.com/v1

Response Format

All API responses are JSON, with Content-Type: application/json.

Example paginated response:


Code
{
  "success": true,
  "message": {
    "permits": [
      {
        "permit": {
          "id": "CAEO000112393",
          "number": "#APP2026-00030",
          "description": "Applicant made small revision to grading and drainage on lot site work. no changes to building landscape etc",
          "status": "applied",
          "labels": "new_construct",
          "ailabels": ["new_construct"],
          "aibuiling_category": "commercial",
          "city_assigned_cost": null,
          "fees": null,
          "inspection_pass_rate": null,
          "timeline": [
            {
              "status": "applied",
              "date": "2026-02-04"
            }
          ],
          "durations": {
            "total_days": 0,
            "construction_days": null,
            "approval_days": null
          }
        },
        "location": {
          "address": {
            "street_address": null,
            "city": "North Fair Oaks",
            "county": "San Mateo",
            "state": "California",
            "zip_code": "94025",
            "zip_plus4": "1840"
          },
          "coordinates": {
            "lat": 37.47305,
            "lng": -122.20266
          },
          "postal_metadata": {
            "delivery_point_barcode": "940251840"
          },
          "jurisdiction": "North Fair Oaks"
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  },
  "errors": null,
  "metadata": {
    "responseId": "response-id",
    "timestamp": "2026-05-20T00:00:00.000Z",
    "version": "v1"
  }
}

When page equals totalPages, there are no additional pages to request.

Pagination

The Kukun API uses page-based pagination. Request a specific page using the page query parameter; control page size with limit (max 1000).

Example:

Code
GET /v1/permits/search?size=10

Code
GET /v1/permits/search...

HTTP Response Codes

The API uses standard HTTP status codes.

Code	Description
200	Success
400	Bad request — malformed syntax or invalid parameter
401	Unauthorized — missing or invalid API key
403	Forbidden — your key does not have access to this resource
404	Not found — the requested resource does not exist
422	Unprocessable entity — request body or parameters failed validation
429	Too many requests — see the Retry-After header
500	Internal server error — contact support if persistent

Error Handling

Validation and request errors return structured JSON responses with a consistent shape:

Example:


Code
{ 
  "error": { "code": "validation_error",
             "message": "The `status` parameter must be one of: applied, issued, in-process, denied, closed, review, expired, inspection.",
             "param": "status"
            }
}

API Versioning

The current API version is:

Code
v1

Versioning is included directly in the request path:

Code
/v1/permits/search

Future API versions may introduce additional capabilities while maintaining backward compatibility whenever possible.

API Reference

The API Reference section documents every endpoint with parameters, authentication, request and response examples, and error responses.

Continue to API Reference section to explore all available endpoints.

Best Practices

To improve performance and result quality:

Filter by date range and geography before broader filters — these are indexed first
Use the smallest limit that meets your needs; the maximum is 1000 per request
For bulk pulls of more than 100K records, contact [email protected] about flat-file delivery
Cache static responses (jurisdiction lists, label taxonomy) — these change infrequently
Respect the Retry-After header on 429 responses

Support

Email [email protected] for authentication, rate-limit, or data-availability issues. Standard response time is one business day. For sales questions, use [email protected].

Last modified on May 21, 2026

Introduction