Placement status

GET /claims/{reference}/placement

Everything about where a placement stands, in one object: the home, the lease, the signatures, the booking and the payments.

{
  "data": {
    "request_id": "d64387dd-…",
    "reference": "REQ-6FED6B",
    "status": "lease_execution",
    "homes": [
      {
        "property_id": "0ba283af-…",
        "property": {
          "name": "USC Village Apartment",
          "address": "3131 South Hoover Street",
          "city": "Los Angeles",
          "state": "California",
          "monthly_rate": 3900,
          "currency": "usd"
        },
        "option_status": "approved",
        "application_status": "approved_to_lease",
        "placed_without_recipient": true,
        "signer": { "name": "Jordan Ellis", "email": "jordan@example.com" },
        "lease": {
          "status": "sent_for_signature",
          "move_in_date": "2026-11-01",
          "move_out_date": "2027-01-31",
          "sent_for_signature_at": "2026-09-21T21:54:18Z",
          "policyholder_signed_at": null,
          "owner_signed_at": null
        },
        "booking": null,
        "payments_succeeded": 0
      }
    ],
    "pay_in_app_url": "https://app.havnly.ai/adjuster/placements"
  }
}

Reading the lease status

`lease.status`	Meaning
`awaiting_lease`	Dates set; the contract is being prepared
`sent_for_signature`	Out for the first signature
`policyholder_signed`	First party has signed; with the landlord to countersign
`fully_signed`	Both signed — payment is unlocked

Also on each home

Field
`recipient_response`	`saved`, `rejected`, or null if they have not answered
`decline_reason`	Why they turned it down, in their words
`proposed_dates`	Different dates they asked for — the placement waits until you answer
`payments`	Each charge: amount, platform fee, type, when it cleared
`deposit_refunds`	Any deposit return requested or made

Answering a date proposal

POST /claims/{reference}/dates/approve-proposal

{ "property_id": "0ba283af-…" }

Accepts the dates the household asked for. The calendar hold moves, the unsigned contract is withdrawn, and a fresh one goes out.

Changing who signs

POST /claims/{reference}/signer

{ "property_id": "0ba283af-…", "signer_name": "Jordan Ellis", "signer_email": "jordan@example.com" }

Reissues the contract to that person. Send no signer_email and the signature comes back to your own team. Either way the previous contract is withdrawn, so there is only ever one live version.

Confirming move-in

POST /claims/{reference}/confirm-move-in

{ "property_id": "0ba283af-…" }

Records that the family actually moved in, which closes the placement’s lifecycle and starts the stay.

Payment

Once fully_signed, the paying party completes payment in Havnly at pay_in_app_url. Rent is charged directly on the landlord’s own Stripe account, so the payment is taken there rather than through this API — Havnly never holds the money, and your systems stay outside PCI scope.

When it clears, the booking is confirmed and booking.confirmed fires.

The whole history, in order

GET /claims/{reference}/timeline

Everything that happened to a request, chronologically — homes added and offered, what the household said and why, dates set and changed, signatures, payments, move-in, documents.

{
  "reference": "REQ-BC08D2",
  "opened_at": "2026-09-22T19:57:49Z",
  "days_open": 11,
  "count": 7,
  "data": [
    { "at": "2026-09-22T19:57:49Z", "type": "request.opened",
      "summary": "Housing request opened",
      "detail": { "reference": "REQ-BC08D2", "bedrooms": 2, "max_budget": 6000 } },
    { "at": "2026-09-22T19:57:51Z", "type": "home.added",
      "summary": "Home added to the request: USC Village Apartment",
      "property_id": "0ba283af-…", "detail": { "property": "USC Village Apartment" } },
    { "at": "2026-09-24T09:12:03Z", "type": "household.responded",
      "summary": "The household declined USC Village Apartment",
      "detail": { "status": "declined", "reason": "Too far from the children's school" } }
  ]
}

Every entry has a machine-readable type and a detail object; the summary is there so a human reading the log does not have to decode it.

This is the call to make when a placement is disputed, or when somebody asks why a family waited eleven days. days_open is included because it is the first thing anyone works out by hand.

Nothing new is recorded to build this. It is assembled from timestamps the platform already kept, so a request opened a year ago has as complete a timeline as one opened this morning.

Types you will see

`type`
`request.opened`	The request was created
`home.added` / `home.offered`	A home was put on the request, then sent to the household
`household.responded`	Their answer — carries the decline reason
`home.placed`	Placed without the household in the loop
`dates.set` / `dates.changed`	Move-in dates, and any later change with both ranges
`lease.sent` / `lease.signed_by_recipient` / `lease.signed_by_owner`	Signature progress
`booking.created` / `move_in.confirmed`	The stay
`payment.succeeded` / `payment.refunded`	Money, with amount and fee
`deposit.refund_requested`	A deposit return was asked for
`document.added`	Paperwork, and whether it arrived over the API

Move-in dates Documents & tours