Rental applications

Convert an applicant into a tenant

Creates a tenant record from an approved application, copying over the applicant's name, contact details, Social Security number, driver's licence, date of birth and current address, then links the tenant back to the application. Requires the rental_applications:write permission.

POST

https://services.magicdoor.com/leasing/company-portal/rental-applications/{id}/tenant-convert

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

idstringrequired

The rental application to work with. A Snowflake id, sent as a decimal string.

example: 1830472847398404096

Response

200 · The tenant. When the application had already been converted, the existing tenant is returned rather than a new one being created.

idstring

The new tenant.

activeboolean

Whether the tenant record is active.

firstNamestring

Tenant's first name, copied from the application.

lastNamestring

Tenant's last name.

emailstring · email

Tenant's email address.

phonestring

Tenant's phone number, formatted for display.

createdstring · date-time

When the tenant was created, in the company's timezone.

updatedstring · date-time

When the tenant last changed, in the company's timezone.

lastSeenstring · date-time

When the tenant last used their portal. Absent when they never have.

lastPortalInvitestring · date-time

When a portal invite was last sent. Absent when none has been.

chatIdstring

The tenant's chat thread. Absent when none exists.

languagestring

The tenant's preferred language code. Absent when none is set.

ssnstring

The tenant's Social Security number, digits only. Absent when none is on file.

driversLicenseobject

Driver's licence details carried over from the application. Absent when none are on file.

dateOfBirthstring · date

Tenant's date of birth. Absent when none is on file.

genderenum<string>

The tenant's gender, when the Tenants service holds one.

emergencyContactsobject[]

Emergency contacts held on the tenant record.

400 · The application's decision is not `approved`. Set the decision first.

400 · The application has no first name, or one shorter than two characters. A tenant cannot be created without it.

409 · The Tenants service refused to create the tenant because it clashes with an existing one. The `reason` member carries what it said.

401 · The access token is missing, expired, or not valid.

403 · The caller is authenticated but does not hold the `rental_applications:write` permission.

404 · No rental application with this id exists, or it belongs to another company. Both cases look identical so that ids cannot be probed across companies.

Safe to call twice

If the application already points at a tenant that still exists, that tenant is returned and nothing new is created.

The applicant's phone may be dropped

If another tenant in the company already uses the applicant's phone number, the tenant is created without a phone number rather than the call failing.