Tenant details and portal access

Saving a tenant, giving them access and inviting them are separate steps. This lets you prepare a tenancy without contacting people before you are ready.

Update a tenant's details

The connection needs Add, update and invite tenants (tenants:write). Use PATCH /api/v1/tenants/TENANT_ID and send only the fields you want to change.

{
  "email": "alex@example.com",
  "phone": "07700 900123"
}

You can update name, email, phone, dateOfBirth, emergencyContact, employmentInfo and portalAccessEnabled. Omitted fields keep their existing value. Nullable fields can be cleared with null; the name cannot be cleared.

If the person is linked to properties outside this key's access, the update will be refused. Their contact details apply to the person across their tenancies.

Enable or disable access

Send a separate update when you want the tenant to be able to use the portal:

{
  "portalAccessEnabled": true
}

For a tenant without an existing linked account, a valid email address is required before enabling access. Setting access to true does not send an email.

To disable portal access, send portalAccessEnabled: false. This does not remove the tenant from their tenancy or delete their record.

Send an invitation explicitly

When you are ready, use POST /api/v1/tenants/TENANT_ID/invite with an empty JSON object and a new idempotency key for that invitation.

curl --request POST \
  'https://app.letted.com/api/v1/tenants/TENANT_ID/invite' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: invite-alex-tenancy-1042-v1' \
  --data '{}'

Replace the placeholders before using this example. The tenant must have portal access enabled, a valid email and no existing linked account. An existing portal user does not need a new invitation through this action.

HTTP 202 means the invitation has been queued, not sent. The response contains data.operationId. Check the operation with GET /api/v1/operations/OPERATION_ID using the same key, or subscribe to tenant.invitation_sent.

That event means the email provider accepted the invitation. It does not prove delivery to the inbox, that the message was opened, or that the tenant signed in.

Preparing an agreement before the tenant joins

Creating an agreement does not send a platform invitation. Always request the invitation explicitly when you want a new tenant to join Letted.

You can create their agreement before they accept or finish signup; it will be waiting when they first sign in. Agreement notification emails require a linked tenant account, subject to portal access and email preferences. An accepted invitation email is not confirmation that the tenant has joined. Check invitation delivery and agreement availability separately.

If an invitation is uncertain

Retry the same request with the same idempotency key after a connection failure. Do not create another request with a different key just because an email has not appeared yet.

If the operation reports failed, check the person's access and delivery before sending another invitation. Contact support with the operation ID if you are unsure.

A useful prompt

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

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

Help me design an invitation checklist for my Letted connection.
Before sending, confirm the tenancy, tenant ID, email address and portal
access. Check whether the person already has an account. Require my approval
before requesting the email, then check the operation result.
Explain any failure before suggesting another invitation.