Matched homes

GET /claims/{reference}/matches

The homes that can actually take this household: verified listings, inside the request’s radius, at or under its budget, with at least the bedrooms asked for — and, for each one, whether it is free for the dates you asked for.

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

{
  "data": [
    {
      "property_id": "0ba283af-98ac-4158-a619-965b3276ef6f",
      "name": "USC Village Apartment",
      "city": "Los Angeles",
      "bedrooms": 2,
      "bathrooms": 2,
      "monthly_rate": 3900,
      "currency": "usd",
      "furnished_status": "furnished",
      "pet_policy": "No Pets",
      "distance_miles": 0.4,
      "over_budget_by": null,
      "available_for_dates": true,
      "conflicts": []
    }
  ],
  "count": 32,
  "available_now": 27,
  "requested_dates": { "move_in": "2026-11-03", "months": 3 },
  "radius_miles": 30,
  "over_budget_pct": 0,
  "measured_from": { "lat": 34.0243, "lng": -118.2851 }
}

Free for the dates first, then nearest. A home that cannot be had is not a better answer for being close.

Availability is the answer that matters

available_for_dates is checked against the whole stay — target_move_in through est_length_months — not just the move-in day. A range can straddle a booked block with both ends free, and that home is not available.

When it is false, conflicts says what is in the way:

"conflicts": [
  { "start_date": "2026-09-20", "end_date": "2026-12-04",
    "reason": "External: Airbnb (Not available)" }
]

Offering a home that is already let costs a cycle: the landlord has to decline, and the household waits. available_now in the envelope is the count worth looking at before you start.

Stretching the budget

max_budget is a hard ceiling by default — the same ceiling an adjuster sees in the portal, so this endpoint never quietly offers a home they could not. When you will go above it, say so per call:

GET /claims/{reference}/matches?over_budget_pct=10

Homes up to 10% over are then included, each with over_budget_by naming the monthly gap. Homes within budget still come back with over_budget_by: null, so one pass tells you both.

Why there is no match score

Havnly scores matches in the portal from a weighted model — location, budget, size, availability, amenities, compliance. That score is not returned here on purpose. A second implementation would drift from the first, and an API that ranks a home differently from the screen your adjuster is looking at is worse than one that ranks nothing.

What you get instead are the inputs that score is built from, so your own system can weigh them your way.

What is excluded, and why

Unverified listings. An incomplete profile cannot be sent for approval — see Is it listed? for what that means to a provider.
Homes over budget, unless you pass over_budget_pct.
Too few bedrooms. The request’s bedrooms is a floor.
Homes not on the market. Withdrawn and let listings never appear.

Unavailable homes are not excluded — they are returned with available_for_dates: false, because knowing a near-perfect home is booked until March is worth more than not seeing it.

measured_from is null when the request has no coordinates. Distance cannot be measured then and the radius is not applied, so send loss_lat and loss_lng. The radius defaults to 25 miles when the request does not set one.

An empty list

Usually the radius is tight, the budget is under the local market, or the request has no coordinates. Sourcing also runs continuously in the background, so a request with nothing today often has homes tomorrow — request.status_changed tells you when that happens.

Asking for more homes

When the list is thin, or you have worked through everything on it, ask Havnly to go looking:

POST /claims/{reference}/source-more

{ "note": "Nothing within 10 miles fits the household" }

{
  "data": {
    "reference": "REQ-6FED6B",
    "notified": true,
    "emailed": true,
    "external_listings": 14
  }
}

202, because this puts a person to work rather than returning an answer. The coordinator assigned to your request is notified in the app and by email, and your note goes with it — tell them what was wrong with what they found, not just that it was not enough.

external_listings is the count of listings already surfaced for this request whose owners have not yet been recruited onto Havnly. Calling those owners is usually the fastest route to a placement, so a high number here means the ask has something to bite on.

There is no cooldown. Working a request is iterative — discard what does not fit, ask again, look again — and the second ask in that loop is the real one.

`409 no_coordinator`

Nobody is assigned to source for this request yet, so the ask would go nowhere. That is ours to fix, not yours.

In sandbox

A sandbox key gets simulated: true and nothing is sent. Test keys do not put work in a real person’s queue.

List and read Place a home