List and read requests

List

GET /claims?limit=25&status=options_sent&updated_since=2026-09-01T00:00:00Z&cursor=…

Parameter
`limit`	Up to 100 per call, 25 by default
`status`	One or more `status_primary` values, comma-separated
`updated_since`	ISO timestamp — only requests that changed since then
`cursor`	`next_cursor` from the previous page

With a thousand live requests, updated_since is how you sync without re-reading everything. next_cursor is null on the last page.

curl 'https://api.havnly.ai/functions/v1/claims?limit=25' \
  -H 'Authorization: Bearer hvn_pk_…'

Newest first, up to 100 per call. Only the requests your organisation submitted — another carrier’s are not yours to see, and neither are requests opened inside Havnly by your coordinators.

{
  "data": [
    {
      "id": "d64387dd-…",
      "claim_ref": "REQ-6FED6B",
      "status_primary": "housing_needs_collected",
      "loss_city": "Los Angeles",
      "loss_state": "California",
      "target_move_in": "2026-11-01",
      "max_budget": 5000,
      "bedrooms": 2,
      "external_reference": "CLM-99812",
      "api_external_id": "YOUR-CLAIM-0001",
      "created_at": "2026-09-21T21:35:42Z"
    }
  ],
  "count": 1
}

Read one

GET /claims/{reference}

By our reference or by id — both work:

curl 'https://api.havnly.ai/functions/v1/claims/REQ-6FED6B' \
  -H 'Authorization: Bearer hvn_pk_…'

Returns the request in full: address, dates, household, budget and payers.

404 means no request with that reference belongs to your organisation.

Statuses

`status_primary`	Where it is
`housing_needs_collected`	Submitted; sourcing has begun
`housing_options_found`	Homes have been found
`options_sent`	Homes are with the household to choose
`awaiting_approval`	Waiting on a decision
`landlord_approval`	With the landlord
`lease_execution`	Contract out for signature
`lease_signed`	Both parties have signed
`payment_setup`	Awaiting payment
`booking_confirmed`	Paid and booked
`move_in_complete`	They have moved in
`in_stay`	Living there
`move_out_closeout`	Stay ending

Rather than polling for these, subscribe to request.status_changed.

Change a request

PATCH /claims/{reference}

{ "max_budget": 6500, "ale_limit": 25000, "rent_payer": "tpa", "target_move_in": "2026-12-01" }

The commercials: budgets and the ALE limit, target move-in and length, search radius, priority, the three payers, your external reference, and the household and adjuster contact details.

What the household needs, which changes constantly after intake — a dog disclosed late, a fifth occupant, a wheelchair nobody mentioned on the phone:

{ "bedrooms": 3, "adults": 3, "children": 2, "has_pets": true,
  "number_of_pets": 1, "pet_details": "1 dog", "pet_breeds": "Labrador",
  "accessibility_needs": ["step-free entry"] }

bedrooms, bathrooms, sqft, adults, children, property_type, furnishing, accessibility_needs, amenities, laundry_preference, parking_preference, and the pet fields. Each of these changes which homes can take the household, so the next /matches reflects it immediately.

Three rules worth knowing:

occupants is derived. Send adults or children and it is recomputed. You cannot set it directly, because a stale occupancy is something a landlord gets told.
Declaring pets means answering for them. has_pets: true needs number_of_pets, pet_details and pet_breeds — the landlord’s first three questions. Sending has_pets: true alone is refused.
Withdrawing pets clears the detail, so no ghost dog is left on the record.

Not changeable: the loss address and who the household is. A different address is a different request, and quietly editing one would move a placement under the people already working it.

If a placement is already under way

Changing what the household needs does not re-open a contract already sent or signed against the old figures, and it does not release a held calendar. When one is in flight you get a 200 that says so:

{
  "data": { "bedrooms": 3, "occupants": 5, "…": "…" },
  "placement_in_progress": {
    "note": "A placement is already under way. These changes apply to matching from now on; they do not alter a lease already sent or signed.",
    "homes": [{ "property_id": "0ba283af-…", "status": "sent_for_signature", "move_in_date": "2026-11-05" }]
  }
}

If the change means that home will no longer do, cancel it — POST /claims/{ref}/cancel-booking — and place again.

Submit many at once

POST /claims/batch

{ "requests": [ { … }, { … } ] }

Up to 50 per call, answered per item:

{
  "created": 49,
  "failed": 1,
  "results": [
    { "index": 0, "external_id": "CLM-1", "ok": true, "data": { "claim_ref": "REQ-6FED6B" } },
    { "index": 1, "external_id": "CLM-2", "ok": false,
      "error": { "code": "invalid_field", "message": "State is required", "field": "loss_state" } }
  ]
}

207 when some worked and some did not — the normal case for a batch, and worth saying rather than flattening to 200 or 400.

Who owns it Matched homes