Create a tenancy

Use this when the applicant process is finished in your other system and you are ready to record the tenancy in Letted. It does not run referencing or generate a tenancy agreement.

What to prepare

You need the property ID, start date, monthly rent and rent due date. You can also include an existing room, end date, deposit details, monthly charges and up to 50 tenants.

Check whether the deposit has actually been paid. Your connection should send depositPaid explicitly: if it is omitted, the API defaults it to true.

For a group handover, select Create tenancies and manage groups and Add, update and invite tenants. Add the relevant view permissions to find the property and check the saved records.

A useful request to give your provider

Read these Letted guides first:
https://app.letted.com/docs/creating-tenancies
https://app.letted.com/docs/api-reference

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

Create a tenancy for the property I select, using the dates, monthly rent
and deposit details I approve. Add both members of the tenant group and
mark one as the lead tenant. Keep portal access disabled for both.

Use one request for the whole group. Do not send invitation emails.
Return the tenancy ID and check the follow-up operation separately.

Example request

For your connection provider: send POST /api/v1/tenancies. All POST and PATCH requests require an Idempotency-Key; see safe retries.

This example uses fictional people. Replace the example property ID with a real ID from a property lookup and confirm all values before sending it. Dates use YYYY-MM-DD; money is in pounds, not pence.

{
  "propertyId": "11111111-1111-4111-8111-111111111111",
  "externalId": "crm-tenancy-1042",
  "startDate": "2027-02-01",
  "rentDueDate": "2027-02-01",
  "rentAmount": 1200,
  "securityDeposit": 1200,
  "depositPaid": false,
  "depositDueDate": "2027-01-25",
  "tenants": [
    {
      "name": "Alex Example",
      "email": "alex@example.com",
      "externalId": "crm-person-201",
      "isLeadTenant": true,
      "portalAccessEnabled": false
    },
    {
      "name": "Sam Example",
      "email": "sam@example.com",
      "externalId": "crm-person-202",
      "portalAccessEnabled": false
    }
  ]
}

The tenancy and group save together. If one part of the request fails validation, the group is not partly saved. Choose at most one lead tenant.

A successful creation returns HTTP 201, the tenancy under data and an operationId. Follow-up work, such as handover and relevant setup tasks, runs after the records are saved. A failure in that follow-up work does not mean the tenancy needs creating again.

Add tenants later

You can create a tenancy without people by omitting tenants or sending an empty list. Add people later with POST /api/v1/tenancies/TENANCY_ID/tenants.

{
  "tenants": [
    {
      "name": "Jamie Example",
      "email": "jamie@example.com",
      "portalAccessEnabled": false
    }
  ]
}

To link a person already in Letted, send their tenantId instead of their name and contact fields:

{
  "tenants": [
    {
      "tenantId": "22222222-2222-4222-8222-222222222222",
      "isLeadTenant": true
    }
  ]
}

The ID above is a placeholder. Linking an existing tenant preserves that person's existing contact details and portal-access setting. It does not send an invitation. Linking the same person to the same tenancy again returns a conflict.

Change the lead tenant

Send PATCH /api/v1/tenancies/TENANCY_ID/lead-tenant with the ID of someone already in the tenancy. This requires both tenancy-write and tenant-write permissions.

{
  "tenantId": "22222222-2222-4222-8222-222222222222"
}

This changes the lead choice; it does not add a person. General tenancy editing, tenant removal and tenancy termination are not API actions in this release.

Understand tenancy status

Future, Ongoing and Expired are calculated from tenancy dates. They are not confirmation that a tenant has physically moved in or out.

Use Tenant details and portal access when you are ready to arrange access and invitations. Optional creation fields are listed in the connection reference.