Quickstart

A housing request submitted, a home placed on it, and a lease out for signature — four calls.

Every example uses a live key. Replace hvn_pk_… with your own from Havnly → API Console → Keys.

1. Submit the housing request

curl -X POST 'https://api.havnly.ai/functions/v1/claims' \
  -H 'Authorization: Bearer hvn_pk_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_id": "YOUR-CLAIM-0001",
    "loss_address": "3131 South Hoover Street",
    "loss_city": "Los Angeles",
    "loss_state": "California",
    "loss_zip": "90007",
    "loss_lat": 34.0243,
    "loss_lng": -118.2851,
    "target_move_in": "2026-11-01",
    "est_length_months": 3,
    "max_budget": 5000,
    "bedrooms": 2,
    "bathrooms": 2,
    "sqft": 1000,
    "adults": 2,
    "children": 1,
    "property_type": "apartment",
    "furnishing": "furnished",
    "rent_payer": "carrier",
    "deposit_payer": "carrier",
    "external_reference": "CLM-99812"
  }'

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

claim_ref is the reference your coordinator will quote. Use it in every call below — or the id, either works.

external_id is your own reference, and it makes the call safe to retry: send the same one twice and you get the first request back with "idempotent": true, never a duplicate.

2. Read the matches

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

Verified homes inside the request’s radius and budget, nearest first, each with distance_miles from the loss address.

3. Put a home on the request

Two ways, depending on whether the household is on Havnly.

They choose — the home is sent to them to accept or decline:

curl -X POST 'https://api.havnly.ai/functions/v1/claims/REQ-6FED6B/options' \
  -H 'Authorization: Bearer hvn_pk_…' \
  -H 'Content-Type: application/json' \
  -d '{ "property_id": "0ba283af-…", "action": "send" }'

You place it — they are not on the platform, so you name who signs instead:

curl -X POST 'https://api.havnly.ai/functions/v1/claims/REQ-6FED6B/options' \
  -H 'Authorization: Bearer hvn_pk_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "property_id": "0ba283af-…",
    "action": "place",
    "signer_name": "Jordan Ellis",
    "signer_email": "jordan@example.com"
  }'

The landlord is told the home has been placed. The signer receives the contract by email and signs in the browser — no Havnly account needed.

4. Set the move-in dates

curl -X POST 'https://api.havnly.ai/functions/v1/claims/REQ-6FED6B/dates' \
  -H 'Authorization: Bearer hvn_pk_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "property_id": "0ba283af-…",
    "move_in": "2026-11-01",
    "move_out": "2027-01-31"
  }'

This is the step that moves everything: the home’s calendar is reserved for those dates, and the lease goes out for signature by itself. Nobody has to approve the dates — you set them, and the lease is where both sides sign to them.

5. Watch it finish

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

Or let it come to you — register a webhook and you are told when the lease is sent, signed, countersigned and the booking is confirmed.

Overview Authentication