Documents and tours

Documents on a request

GET /claims/{reference}/documents

{
  "data": [
    {
      "id": "9f1c…",
      "file_name": "Lease - Riverside 2BR.pdf",
      "file_type": "application/pdf",
      "document_type": "lease",
      "document_status": "approved",
      "created_at": "2026-10-28T11:20:00Z",
      "download_url": "https://…",
      "download_url_expires_in": 3600
    }
  ]
}

Links are signed and short-lived — an hour. A permanent URL to somebody’s lease or identity document is not a thing to hand out, so fetch the link when you need the file rather than storing it.

Attaching a document

POST /claims/{reference}/documents

The declaration page and the authorisation letter are already in your claim folder. Send them with the request rather than making someone re-upload them in a browser — a placement should not wait a day on a file you already had.

{
  "file_name": "Policy declaration page.pdf",
  "content_type": "application/pdf",
  "document_type": "policy_declaration",
  "content_base64": "JVBERi0xLjQK…"
}

{
  "data": {
    "id": "7de6a708-…",
    "file_name": "Policy declaration page.pdf",
    "file_type": "application/pdf",
    "file_size": 284113,
    "document_type": "policy_declaration",
    "document_status": "uploaded",
    "created_at": "2026-09-22T18:22:32Z"
  }
}

document_type is your own label — policy_declaration, authorisation, damage_photos, whatever your system calls it. It comes back on every read.

A data: prefix on content_base64 is accepted and stripped, because enough systems emit one that refusing it would be a support ticket rather than a standard.

Limits

Anything executable is refused outright. These files are served back to households and landlords through signed links, so the bucket is not a place to put a script.

Requires the claims:write scope.

Removing a document

DELETE /claims/{reference}/documents/{id}

For the wrong file, or the superseded one. You may remove documents your integration uploaded, and nothing else: a file the household or a Havnly coordinator put on the request is not yours to delete, and trying returns 403 not_yours.

The stored file goes with the record — no orphan left behind.

Tours

GET /claims/{reference}/tours

Whether the household has actually seen a home, and when:

{
  "data": [
    {
      "id": "3a21…",
      "property_id": "0ba283af-…",
      "tour_date": "2026-10-18",
      "tour_time": "14:00",
      "tour_type": "in_person",
      "status": "completed",
      "completed_at": "2026-10-18T14:45:00Z",
      "properties": { "name": "Riverside 2BR", "city": "Los Angeles" }
    }
  ]
}

Statuses: pending (awaiting the landlord), confirmed, completed, cancelled.

Tours are requested by the household in Havnly. At volume, this endpoint mostly answers a different question: which placements are stalled because nobody has viewed the home yet.