# api.insure API reference

Base URL `https://api.insure`, JSON over HTTPS, contract at `/openapi.json`. Reads are keyless.

## Claims

The claim file, from first notice to payment. A claim waiting on a license is typed as waiting, never left in an untyped queue.

### GET /claims

The claims collection. Filter by peril or stage. A filter that matches nothing answers a typed EMPTY, never a bare list.

Response 200 · OK:

```json
{
  "type": "OK",
  "claims": [
    {
      "claim": "clm_8f3ka92",
      "peril": "wind_hail",
      "stage": "evaluate",
      "status": "PENDING_ADJUSTER"
    },
    {
      "claim": "clm_7d21m40",
      "peril": "water_nonweather",
      "stage": "decide",
      "status": "DECIDED"
    }
  ]
}
```

### POST /claims

First notice of loss. Opens the claim, starts the state's clocks, and runs the open work: intake, acknowledgment, file assembly, coverage and estimate review.

Request:

```json
{
  "policy": "HO3-4482-TX",
  "loss": {
    "date": "2026-07-14",
    "peril": "wind_hail",
    "state": "TX"
  },
  "posture": "first_party"
}
```

Response 202 · OK:

```json
{
  "type": "OK",
  "claim": "clm_8f3ka92",
  "stage": "notice",
  "openWork": [
    "intake",
    "acknowledge",
    "assemble",
    "coverage",
    "estimate"
  ],
  "clocks": {
    "acknowledge": {
      "rule": "TX: 15 days",
      "started": "2026-07-15",
      "due": "2026-07-30"
    }
  },
  "webhooks": ["decision.issued", "claim.paid"]
}
```

### GET /claims/:id

One claim, with its stage, open work and clock state. At the reserved act it answers PENDING_ADJUSTER and names the license the act requires.

Waits on a licensed adjuster.

Response 200 · OK:

```json
{
  "type": "OK",
  "claim": "clm_8f3ka92",
  "policy": "HO3-4482-TX",
  "line": "homeowners",
  "posture": "first_party",
  "stage": "evaluate",
  "status": "PENDING_ADJUSTER",
  "openWork": {
    "fnol": "complete",
    "acknowledgment": "sent",
    "file": "assembled",
    "coverage": "analyzed",
    "estimate": "checked"
  },
  "reservedAct": {
    "verb": "adjust",
    "license": "TX all-lines adjuster",
    "verified": "at_call_time",
    "authority": "delegated_by_carrier",
    "fee": { "shape": "flat", "fixed": "at_post" }
  },
  "clocks": {
    "acknowledge": {
      "rule": "TX: 15 days",
      "closed": "2026-07-16"
    },
    "decide": {
      "rule": "TX: 15 business days",
      "started": "2026-07-24",
      "due": "2026-08-14"
    }
  }
}
```

## Coverage

Rating is open work, so a rate answers at once. Offering, negotiating and binding are producer-reserved, so a bind waits on a licensed producer.

### POST /quotes

Price coverage for a risk in one state and line. The quote holds its premium until it expires.

Request:

```json
{
  "line": "personal_auto",
  "state": "TX",
  "risk": {
    "vehicle": "2024 Subaru Outback",
    "garaging": "78704"
  },
  "coverages": [
    "liability",
    "collision",
    "comprehensive",
    "gap"
  ],
  "term": "6_months"
}
```

Response 200 · OK:

```json
{
  "type": "OK",
  "quote": "qt_31c8f0",
  "premium": {
    "amount": 650,
    "currency": "USD",
    "term": "6_months"
  },
  "expires": "2026-08-12"
}
```

### POST /quotes/:id/bind

Bind a quote. The call answers PENDING_PRODUCER while a licensed producer reviews and binds, then policy.bound arrives with the policy number.

Waits on a licensed producer.

Response 202 · OK:

```json
{
  "type": "OK",
  "quote": "qt_31c8f0",
  "status": "PENDING_PRODUCER",
  "reservedAct": {
    "verb": "bind",
    "license": "TX general lines producer",
    "verified": "at_call_time",
    "fee": { "shape": "flat", "fixed": "at_post" }
  },
  "webhooks": ["policy.bound", "documents.issued"]
}
```

### GET /policies/:id

One policy record at ACORD grain: form, term, coverages and deductibles.

Response 200 · OK:

```json
{
  "type": "OK",
  "policy": "HO3-4482-TX",
  "form": "HO-3",
  "insured": "Jordan Alvarez",
  "term": {
    "effective": "2026-03-01",
    "expires": "2027-03-01"
  },
  "coverages": {
    "dwelling": 412000,
    "otherStructures": 41200,
    "personalProperty": 206000
  },
  "deductible": { "windHail": "2%" }
}
```

## Documents

The documents a claim or a renewal runs on, normalized to one shape.

### GET /loss-runs/:id

A normalized loss run: claims and incurred losses for a policy over a stated period.

Response 200 · OK:

```json
{
  "type": "OK",
  "lossRun": "lr_4482tx_5y",
  "policy": "HO3-4482-TX",
  "years": 5,
  "claims": 2,
  "incurred": 22610,
  "valued": "2026-07-31"
}
```

### GET /acord-forms

ACORD forms, normalized. Filter by form number.

### GET /cois

Certificates of insurance at ACORD 25 grain.

### GET /eobs

Explanations of benefits, normalized.

## Events

Webhooks carry each reserved act's result back to your product. decision.issued and policy.bound release the meter; claim.paid and documents.issued are records.

### EVENT decision.issued

The adjuster's decision and their attestation, with the pay clock it starts. A denial is a decision too, and arrives with its reasons.

Payload:

```json
{
  "event": "decision.issued",
  "claim": "clm_8f3ka92",
  "stage": "decide",
  "status": "DECIDED",
  "decision": {
    "outcome": "approved",
    "by": "licensed_adjuster",
    "license": "TX all-lines adjuster",
    "attestation": "att_71b0e4",
    "at": "2026-07-29T15:20:00Z"
  },
  "clocks": {
    "pay": {
      "rule": "TX: 5 business days",
      "started": "2026-07-29",
      "due": "2026-08-05"
    }
  },
  "meter": "released"
}
```

### EVENT claim.paid

The payment record once the payment is issued, with the decision it pays.

Payload:

```json
{
  "event": "claim.paid",
  "claim": "clm_8f3ka92",
  "stage": "pay",
  "status": "DECIDED",
  "decision": {
    "outcome": "approved",
    "by": "licensed_adjuster",
    "attestation": "att_71b0e4",
    "at": "2026-07-29T15:20:00Z"
  },
  "payment": {
    "record": "pay_20c4d1",
    "amount": 14210,
    "currency": "USD",
    "issued": "2026-07-31"
  }
}
```

### EVENT policy.bound

The bound policy number and its effective date, once a licensed producer binds.

Payload:

```json
{
  "event": "policy.bound",
  "quote": "qt_31c8f0",
  "policy": "PAP-7741-TX",
  "effective": "2026-08-03",
  "meter": "released"
}
```

### EVENT documents.issued

The policy's documents: ID cards and the declarations page.

Payload:

```json
{
  "event": "documents.issued",
  "policy": "PAP-7741-TX",
  "documents": ["id_cards", "declarations"]
}
```

## How it refuses

| Status | Type | When |
| --- | --- | --- |
| 200 | EMPTY | A filter matched nothing. The body says what was asked. |
| 401, 403 | BLOCKED | A key or scope can't reach this route. Reserved scopes answer with a worded reason. |
| 402 | OFFER | The request would pass your spend ceiling. The body carries the re-authorization offer. |
| 404 |  | The claim, quote or policy doesn't exist. |
| 422 |  | The request is missing a required field, such as the loss date or state on a first notice. |