Place a home on a request

POST /claims/{reference}/options

Two ways to put a home on a housing request, depending on whether the household is using Havnly.

Review the budget first

A home cannot be sent or placed until its budget has been approved — the same rule the adjuster portal applies. Start by reading what it will actually cost:

GET /claims/{reference}/options/{propertyId}/budget

{
  "property": "USC Village Apartment",
  "currency": "usd",
  "stay": { "months": 6, "target_move_in": "2027-05-01" },
  "monthly": {
    "list_rate": 3900,
    "rent_tier": 3800,
    "tier_applied": "4-6 months",
    "pet_rent": 0, "utilities": 0,
    "total": 3800
  },
  "one_off":  { "cleaning_fee": 200, "application_fee": 0, "pet_fee": 0, "total": 200 },
  "deposits": { "security_deposit": 1500, "pet_deposit": 0, "total": 1500, "refundable": true },
  "havnly_fee": { "percent": 12, "applies_to": "rent only", "per_month": 456, "over_stay": 2736 },
  "totals": {
    "rent_over_stay": 22800,
    "cost_of_stay": 23000,
    "first_payment": 5500,
    "deposits_refundable": 1500
  },
  "against_budget": {
    "max_budget": 3600,
    "within_budget": false,
    "monthly_over_by": 200,
    "ale_limit": 45000,
    "ale_consumed_by_stay": 23000,
    "within_ale_limit": true
  },
  "approval": { "budget_approved": false, "approved_at": null, "on_request": true }
}

tier_applied is the line to read first. A six-month stay bills at the 4–6 month tier — $3,800, not the $3,900 list rate. Longer stays cost less per month, and the figure here is the one the checkout will charge, because both use the same ladder.

Deposits are excluded from ale_consumed_by_stay because they come back. They are in first_payment, which is what the payer is actually asked for on day one.

The Havnly fee applies to rent only — never to deposits, pet rent, utilities or one-off fees.

Approving it

POST /claims/{reference}/options/{propertyId}/budget

{ "approved": true }

Returns the figures that were approved, so the response is a record of what was agreed rather than a bare acknowledgement. Send "approved": false to withdraw an approval.

If you have already reviewed the cost in your own system, you can approve and place in one call instead:

{ "property_id": "0ba283af-…", "action": "place", "approve_budget": true }

Without an approval, POST /options answers 409 budget_not_approved.

Send it to them to choose

{ "property_id": "0ba283af-…", "action": "send" }

They are emailed the home, review it, and apply for the one they want. The landlord approves the application, and you set the dates.

Use this when the household has a Havnly login — they see the homes, compare them, and choose.

Place it yourself

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

Use this when they are not on the platform and will not be. The home is booked on their behalf: the landlord is told, and the lease goes to the person you name, who signs it in the browser with no account. Leave the signer out and it comes to your own team instead.

The household is not contacted at all on this path.

{
  "data": {
    "request_id": "d64387dd-…",
    "property_id": "0ba283af-…",
    "option_status": "approved",
    "application_status": "approved_to_lease",
    "budget_approved": true,
    "adjuster_placed_at": "2026-09-21T21:54:15Z"
  }
}

Either way the home’s budget is approved by the call — submitting it through the API is your approval that the carrier will fund this rent.

Errors worth handling

Next: set the move-in dates.