{"openapi":"3.0.3","info":{"title":"California NHD Public API","version":"1.0.0","description":"REST API for partners (escrow software, MLS providers, brokerage CRMs) to programmatically order Natural Hazard Disclosure reports and receive webhook notifications when reports complete.","contact":{"name":"California NHD Support","email":"support@californianhd.com"}},"servers":[{"url":"https://californianhd.com/v1","description":"Production v1 API"}],"security":[{"bearerAuth":[]}],"paths":{"/reports":{"post":{"summary":"Create a new NHD report","description":"Submits a property address and contact info, then begins the asynchronous report generation pipeline. Returns immediately with a report ID; subscribe to webhooks or poll GET /reports/{id} to know when it's ready.","tags":["Reports"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportRequest"},"example":{"propertyAddress":"1908 Vintage Ln, Fairfield, CA 94534","apn":"0134-142-080","agentName":"Jane Smith","agentEmail":"jane@example.com"}}}},"responses":{"202":{"description":"Accepted — report generation started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Monthly quota exceeded"}}}},"/reports/{id}":{"get":{"summary":"Get report status","tags":["Reports"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Report status (and signed PDF URL when ready)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"401":{"description":"Missing or invalid API key"},"403":{"description":"Report does not belong to this API key"},"404":{"description":"Report not found"}}}},"/openapi.json":{"get":{"summary":"OpenAPI specification","tags":["Meta"],"responses":{"200":{"description":"OpenAPI 3.0 document","content":{"application/json":{}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Use your API key as the bearer token: `Authorization: Bearer cnhd_live_…`"}},"schemas":{"CreateReportRequest":{"type":"object","required":["propertyAddress"],"properties":{"propertyAddress":{"type":"string","description":"California property address. Non-California addresses are rejected."},"apn":{"type":"string","description":"Assessor's Parcel Number (optional but recommended)"},"propertyType":{"type":"string"},"escrowOfficerName":{"type":"string"},"escrowOfficerEmail":{"type":"string","format":"email"},"escrowOfficerPhone":{"type":"string"},"agentName":{"type":"string"},"agentEmail":{"type":"string","format":"email"},"agentPhone":{"type":"string"}}},"Report":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoiceNumber":{"type":"string"},"status":{"type":"string","enum":["pending","geocoding","hazard_assessment","pdf_generation","email_delivery","completed","failed"]},"reviewStatus":{"type":"string"},"propertyAddress":{"type":"string"},"apn":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"downloadUrl":{"type":"string","nullable":true,"description":"Signed PDF download URL — present only when status='completed'. Token expires after 7 days."}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"string"}}}}},"x-webhooks":{"events":["report.completed","report.failed","payment.refunded"],"signing":"Each delivery includes `X-CaliforniaNHD-Signature: t=<timestamp>,v1=<hex>`. Compute HMAC-SHA256 of `<timestamp>.<rawBody>` using your subscription's signing secret and compare in constant time.","retries":"Failed deliveries (non-2xx response or network error) retry with exponential backoff: 30s, 2m, 10m, 30m, 2h, 6h. After 6 failed attempts the delivery is marked as failed.","examplePayload":{"id":"evt_abc123","event":"report.completed","createdAt":"2026-05-03T19:30:00Z","data":{"reportId":"550e8400-e29b-41d4-a716-446655440000","invoiceNumber":"NHD-20260503-001","propertyAddress":"1908 Vintage Ln, Fairfield, CA 94534","downloadUrl":"https://www.californianhd.com/api/submissions/.../report?token=..."}}}}