Partner API Documentation

Programmatically order Natural Hazard Disclosure reports and receive webhook notifications. Ideal for escrow software, MLS providers, and brokerage CRMs.

API v1 · REST · JSON · HMAC-SHA256 webhooks · OpenAPI 3.0 spec

Quickstart

1. Get an API key

Email partners@californianhd.com to request access. We'll provision a key and configure your monthly quota.

2. Create your first report

Send a POST request to /v1/reports with a Bearer token and a JSON body containing propertyAddress, agentName, and agentEmail.

3. Receive a webhook when it's ready

Subscribe to the report.completed event and we'll POST a signed JSON payload to your URL with a download link.

Authentication

All requests must be authenticated with your API key using either an Authorization: Bearer header or an X-API-Key header. Keys are prefixed cnhd_live_ followed by 32+ random characters. Store them as environment variables — never commit to source control.

Quotas

Each key has a monthly request limit. Exceeded quotas return 429 Too Many Requests.

Rotation & Revocation

Compromised keys can be rotated (generates a new secret, preserves usage history) or revoked (instant deactivation). Contact partners@californianhd.com immediately if a key is exposed.

Reports API

POST /v1/reports

Create a new NHD report. Returns HTTP 202 immediately — report generation is asynchronous (typically 30–90 seconds).

Request body fields: propertyAddress (required), apn (optional, recommended), propertyType, agentName, agentEmail, escrowOfficerName, escrowOfficerEmail.

GET /v1/reports/:id

Poll for status. Once status is completed, the response includes a signed PDF download URL valid for 7 days.

Status values

  • pending — just created
  • geocoding — resolving address
  • hazard_assessment — querying CAL FIRE / FEMA / USGS
  • pdf_generation — rendering report
  • completed — ready, downloadUrl populated
  • failed — see report.failed webhook for details

Webhooks

We POST a JSON payload to your subscription URL whenever a subscribed event occurs.

Supported events

  • report.completed — a report finished generating successfully
  • report.failed — pipeline failed; data.error contains the reason
  • payment.refunded — an admin refunded a previously paid report

Signature verification

Each request includes X-CaliforniaNHD-Signature: t=<timestamp>,v1=<hex>. Compute HMAC-SHA256 over `${timestamp}.${rawBody}` using your subscription's signing secret and compare in constant time.

Retries

Non-2xx responses are retried with exponential backoff: 30s, 2m, 10m, 30m, 2h, 6h. After 6 failed attempts the delivery is marked as failed. Your endpoint must respond within 10 seconds.

Subscribing

Contact partners@californianhd.com with your endpoint URL and the events you want to receive.

Errors

All errors return a standard JSON shape with an error string and optional details array.

HTTP status codes

  • 200/202 — success
  • 400 — invalid request body
  • 401 — missing or invalid API key
  • 403 — report does not belong to your key
  • 404 — report not found
  • 429 — rate limit or monthly quota exceeded
  • 5xx — server error; safe to retry with exponential backoff