Residents

Read resident records for your workspace. Personal data — scope the key accordingly.

GET /api/agent/residents
GET /api/agent/residents/{id}
Authorization: Bearer <key>

Requires the residents:read scope.

This endpoint returns personal data about real people. Give the scope only to integrations that genuinely need it, and never to a key embedded in a public website. A listings key and a residents key should be two different keys — see Authentication.

Filters

Parameter	Type	Notes
`building`	string
`unit`	string
`email`	string	Exact match on the address held on the record.
`search`	string	Free text.
`paymentStatus`	`pending` \| `paid` \| `refunded` \| `cancelled` \| `failed`
`signNowStatus`	`pending` \| `sent` \| `partially_signed` \| `signed` \| `declined` \| `expired`	Contract signature progress.
`page`, `limit`	integer	`limit` is capped at 50.

An unrecognised value for either status parameter is rejected rather than ignored, so a typo fails loudly instead of silently widening your query.

Response

{
  "ok": true,
  "data": {
    "residents": [ ... ],
    "pagination": { "page": 1, "limit": 50, "total": 128, "totalPages": 3 }
  }
}

The limit cap of 50 is much lower than the catalogue's 500. That is deliberate: bulk-exporting personal data should be a conscious, paginated act, not a single convenient request.

A resident is a reservation

There is no separate "resident" entity. A resident record is the tenancy — the contract, the pricing, the ledger and the departure all hang off it. Someone who has lived in two units has two records, correctly, because they had two tenancies.

This matters when you match on email: one address can legitimately return several records, including ended ones. See The tenancy lifecycle.

Not in this API

Money movement, invoices and ledger entries are not exposed here. The API is read-oriented and narrow by design; billing is not a surface an external integration should be driving. See The ledger for what those records look like inside the product.

Properties
Errors — in particular, why a 404 may mean "not yours"

Filters

Response

A resident is a reservation

Not in this API

Related

On this page