Submit a housing request

POST /claims

One call opens a housing request: the household, where they need to live, for how long, and who pays. It takes the same fields as the form your coordinators use, and enforces the same required set — a request that arrives without a budget or a move-in date cannot be sourced, whichever door it came through.

Minimal request

Everything here is required.

{
  "loss_address": "3131 South Hoover Street",
  "loss_city": "Los Angeles",
  "loss_state": "California",
  "loss_zip": "90007",
  "target_move_in": "2026-11-01",
  "est_length_months": 3,
  "bedrooms": 2,
  "bathrooms": 2,
  "sqft": 1000,
  "adults": 2,
  "property_type": "apartment",
  "furnishing": "furnished",
  "rent_payer": "carrier",
  "deposit_payer": "carrier"
}

{
  "data": {
    "id": "d64387dd-67cc-427a-85aa-20c6387e5c0b",
    "claim_ref": "REQ-6FED6B",
    "status_primary": "housing_needs_collected",
    "created_at": "2026-09-21T21:35:42Z"
  }
}

201 Created. Sourcing begins immediately: the request is matched against verified homes, and our crawler starts looking in that postcode.

Send coordinates when you have them

loss_lat and loss_lng are optional but matter. Postcode proximity uses a US ZIP table, so a Canadian or non-US postcode cannot be matched by postcode at all — with coordinates the search works anywhere.

Retrying safely

Send external_id — your own reference for the request:

{ "external_id": "CLM-99812-HOUSING", "loss_address": "…" }

A repeat of the same external_id returns the request you already created, with "idempotent": true. A dropped connection therefore costs you nothing, and your claim system never opens the same housing request twice.

Idempotency-Key as a header does the same thing.

What you get back

Field	Meaning
`id`	Havnly’s id for the request — use it or `claim_ref` in later calls
`claim_ref`	The human reference, `REQ-XXXXXX`, quoted by everyone involved
`status_primary`	Where the request is in its lifecycle
`created_at`	When it opened

See the field reference for everything you can send.

Authentication Field reference