Skip to content
Letted DocsGo to Letted

Find properties and records

Make sure your connection is working with the right property and people.

Every record has an ID: a unique reference assigned by Letted. Your connection should look up these IDs rather than guess them or copy them from browser address bars.

Find a property first

Ask your connection to list properties and match the address and postcode. If there is more than one possible match, have it ask you to choose.

Text to copy
Read these Letted guides first:
https://app.letted.com/docs/working-with-records
https://app.letted.com/docs/api-reference

If you cannot open them, ask me to paste the pages rather than guessing.

List the Letted properties available to this connection. Help me identify
[property address] by checking both its address and postcode.
Do not create or update anything. If the match is unclear, ask me.

For your connection provider: use GET /api/v1/properties with properties:read permission.

bash
curl 'https://app.letted.com/api/v1/properties?limit=50' \
  --header 'Authorization: Bearer YOUR_API_KEY'

The response contains data, a list of properties, and nextCursor. Each property includes its id, address, postcode, isHmo and a link to open it in Letted.

Find a room

If the tenancy is for a room, retrieve the rooms belonging to the chosen property. Rooms must already exist in Letted.

http
GET /api/v1/rooms?propertyId=PROPERTY_ID

The same properties:read permission covers rooms. A room includes id, propertyId and name. You cannot attach a room from a different property to a tenancy.

Find tenancies, tenants and tasks

Use the appropriate view permission for each type of record. Replace PROPERTY_ID below with the real property ID.

http
GET /api/v1/tenancies?propertyId=PROPERTY_ID
GET /api/v1/tenants?propertyId=PROPERTY_ID
GET /api/v1/tasks?propertyId=PROPERTY_ID

To retrieve one record, put its ID in the path:

http
GET /api/v1/tenancies/TENANCY_ID
GET /api/v1/tenants/TENANT_ID
GET /api/v1/tasks/TASK_ID

The same single-record pattern also works for properties and rooms. A single result is returned under data; lists return an array under data.

Tenancy information includes tenant IDs with their lead-tenant choices, plus agreement IDs, statuses and sent/completed dates. It does not include agreement documents. Task information includes its category, priority, due date, status and a link to open it in Letted.

Read more than one page

Lists return up to 50 records by default. Set limit between 1 and 100. When nextCursor is not null, use it as after in the next request, keeping the same filters.

http
GET /api/v1/tasks?propertyId=PROPERTY_ID&limit=50&after=NEXT_CURSOR

Stop when nextCursor is null. An empty result may mean there are no matching records within the key's property access.

Match a record to your other system

When creating a tenancy, a new tenant or a task, your connection can supply an externalId, such as crm-tenancy-1042. It can then look up the record using that reference:

http
GET /api/v1/tenancies?externalId=crm-tenancy-1042

References are unique within an organisation and record type, and are shared across its keys. They are separate from the ID assigned by Letted. Reusing an existing reference to create another record returns a conflict; it does not update the first record.

Letted does not merge tenants because they have the same email address. To link an existing person, find and use their tenant ID. Tenant lookups include people linked to tenancies at accessible properties; they do not expose every unlinked contact.