Copy page

Documentation

Kukun API Quickstart

The Kukun Permits API provides filtered search across 800M+ 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

800M+ 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:

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

---

AVM & PICO

Resolve a property by address or Kukun ID, then retrieve its automated valuation estimate, property score, and neighborhood score. See the API Reference for full parameters and examples.

Features include:

• Automated Valuation Model (AVM) with low/high confidence range
• Property Score and Neighborhood Score (0-1000 scale)
• Resolve by structured address or known kukun-id
• Structured, versioned API responses

---

Property Investment Outlook (KIO)

A proprietary, predictive metric forecasting real estate appreciation with a property 5-year value forecast.

---

Property Details (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 sales@mykukun.com 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 sales@mykukun.com 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": "FGEO00X088",
          "number": "#XXXXX-XXXXX",
          "description": "Remodeling of the kitchen. the existing wall located where the sink is will move outwards to create more space in the kitchen",
          "status": "applied",
          "labels": "residential, addition alteration to existing residence",
          "tags": ["kitchen-remodel"],
          "type": "residential",
          "city_assigned_cost": null,
          "fees": null,
          "inspection_pass_rate": null,
          "timeline": [
            {
              "status": "applied",
              "date": "2025-07-11"
            }
          ],
          "durations": {
            "total_days": 0,
            "construction_days": null,
            "approval_days": null
          }
        },
        "contractor": {
          "id": "324655",
          "company_name": "Company Name",
          "company_phone": "5649873211",
          "business_type": null,
          "address": {
            "street": "123 Main St",
            "city": "Kansas City",
            "county": "Jackson",
            "state": "MO",
            "zip_code": "64113",
            "plus4_code": "2628",
            "formatted": "123 Main St, Kansas City, MO 64113"
          }
        },
        "property": {
          "type": "residential",
          "subtype": "single_family",
          "year_built": 1970,
          "lot_size_sqft": 36176,
          "building_area_sqft": 7680,
          "stories": null,
          "owner": {
            "name": "Owner Name",
            "phone": 5649873211
          },
          "valuation": {
            "market_value": 0
          }
        },
        "location": {
          "address": {
            "id_address": 324234324,
            "street_address": "123 Main St",
            "city": "Kansas City",
            "county": "Jackson",
            "state": "MO",
            "zip_code": "64113",
            "zip_plus4": "3925"
          },
          "coordinates": {
            "lat": 28.300478,
            "lng": -82.613849
          },
          "postal_metadata": {
            "delivery_point_barcode": "654321321321568"
          },
          "jurisdiction": ["San Mateo"]
        }
      }
    ],
    "total": 139,
    "limit": 1,
    "total_pages": 139,
    "next_page_id": "WzAsIk1ORFUwMDAwODEwOTQQ=="
  },
  "errors": null,
  "metadata": {
    "responseId": "8e4b43ff9b4709cac2b9d428376asd",
    "timestamp": "2026-05-27T00:00:00.000Z",
    "version": "v1"
  }
}

When next_page_id is null or omitted, there are no additional pages to request.

---

Pagination

The Kukun API uses cursor-based pagination (scroll / search-after). Control page size with limit (max 1000, default varies by endpoint). Each response includes:

• total - total number of records matching the query, across all pages
• limit - number of records returned in this response
• total_pages - total number of pages available at the current limit
• next_page_id - opaque cursor pointing to the last record in this result set; pass it back in as next_page_id on the next request to continue

Example response:

Code
{
  "total": 447700,
  "limit": 1000,
  "total_pages": 448,
  "next_page_id": "WzAsIkZMQUwwMDAwMDIzODQiXQ=="
}

Next page:

Code
GET /v1/permits/search?limit=1000&next_page_id=WzAsIkZMQUwwMDAwMDIzODQiXQ==

---

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
502	Bad gateway — upstream dependency returned an invalid response
503	Service unavailable — upstream dependency is temporarily unavailable
504	Gateway timeout — upstream dependency timed out

---

Error Handling

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

Example:

Code
{
  "success": false,
  "message": null,
  "errors": {
    "statusCode": 400,
    "code": "validation_error",
    "message": "Provide either `kukun-id` or all of `address`, `city`, `state`, and `zip-code`.",
    "details": [
      {
        "field": "state",
        "message": "State must be provided when resolving by address."
      }
    ]
  },
  "metadata": {
    "responseId": "8e4b43ff9b4709cac2b9d428376asd",
    "timestamp": "2026-05-27T00:00:00.000Z",
    "version": "v1"
  }
}

---

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 sales@mykukun.com about flat-file delivery
• Cache static responses (jurisdiction lists, label taxonomy) — these change infrequently
• Respect the Retry-After header on 429 responses

---

Support

Email partner.support@mykukun.com for authentication, rate-limit, or data-availability issues. Standard response time is one business day. For sales questions, use sales@mykukun.com.