Tenants

Create a tenant

Creates a tenant and the MagicDoor sign-in that goes with them, and can send their portal invite in the same call. The response carries the password the tenant will sign in with — it is the only time you can read it.

POST

https://api.portal.magicdoor.com/company-app/tenants

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.

Body

application/json

Only firstName is required. Email and phone, if sent, must not already belong to another tenant in the company.

firstNamestringrequired

Given name. 1 to 150 characters.

lastNamestring

Family name. 1 to 150 characters.

emailstring · email

Email address. Up to 250 characters, and must be unique within the company.

phonestring

Phone number. Must be a valid number and unique within the company.

languagestring

ISO 639-1 language code for messages to this tenant, for example en or es.

ssnstring

Social Security number. Validated as a federal id. Sending it stores a government identifier against the tenant.

driversLicenseobject

Driver's licence details.

dateOfBirthstring · date

Date of birth, as YYYY-MM-DD.

genderenum<string>

Recorded gender.

malefemaleotherpreferNotToSay

currentAddressobject

Where the tenant currently lives. Sending this replaces the whole address.

emergencyContactsobject[]

People to contact in an emergency. Sending this replaces the whole list.

iconsstring[]

Icon keys to pin to the tenant. Sending this replaces the whole list.

passwordstring

The password to give the tenant. 5 to 150 characters. Leave it out and MagicDoor generates one, which comes back in the response.

sendPortalInviteboolean

true sends the company's tenant portal invite templates to this tenant straight away. If the invite fails to send the tenant is still created — resend it with send a tenant portal invite.

Response

200 · The new tenant, plus the password they will sign in with.

idstring

The tenant. This is the person, not their place on any particular lease.

activeboolean

false once the tenant has been deactivated. A deactivated tenant cannot sign in and cannot be given a new password.

emailstring

Email address. Absent when none is on file.

firstNamestring

Given name.

lastNamestring

Family name. Absent when only a first name is on file.

phonestring

Phone number, formatted for reading. Absent when none is on file.

createdstring · date-time

When the tenant record was created.

updatedstring · date-time

When the tenant record was last changed.

lastSeenstring · date-time

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

lastPortalInvitestring · date-time

When a portal invite was last sent. Absent when none ever was.

portalStatusenum<string>

Where the tenant is in getting onto the tenant portal: notInvited (never invited), invited (invited but never signed in), active (has signed in).

notInvitedinvitedactive

chatIdstring

The tenant's conversation with the company. Absent when no conversation exists.

languagestring

ISO 639-1 language code used for messages to this tenant.

ssnstring

The tenant's Social Security number, if one was recorded. Returned in full, so treat every response containing it as sensitive. No example is shown here on purpose.

driversLicenseobject

Driver's licence details, if recorded. Returned in full, so treat it as sensitive. No example is shown here on purpose.

dateOfBirthstring · date

The tenant's date of birth, if recorded. No example is shown here on purpose.

genderenum<string>

The tenant's recorded gender. Absent when not recorded.

malefemaleotherpreferNotToSay

currentAddressobject

Where the tenant currently lives, as recorded on the tenant record. This is not derived from their lease.

emergencyContactsobject[]

People to contact in an emergency.

iconsstring[]

Icon keys a property manager has pinned to the tenant. Always present, possibly empty.

imageIdstring

The tenant's photo. Absent when they have none.

passwordstring

The password the tenant can now sign in with — either the one you sent or the one MagicDoor generated. Returned here and nowhere else. No example value is shown.

409 · The email address or phone number already belongs to another tenant in the company. `errors` maps the offending field to its message. This particular response is built by hand rather than by the usual problem-details machinery, so unlike every other error on this page it carries no `type`, no `instance` and no `traceId`.

401 · The access token is missing, expired, or does not belong to a property manager.

A tenant is not a lease tenant

A tenant is a person: one record per human being, with their contact details, their identity documents and their portal sign-in. A lease tenant is that person's place on one particular lease, with its own move-in and move-out dates. The same tenant can be a lease tenant on several leases at once, and stays a tenant after every one of them ends. Endpoints under a lease manage lease tenants; the endpoints here manage the person.

The password is in the response

The password field of the response holds the tenant's sign-in password in clear text. It is returned once, at creation, and no endpoint will give it to you again. Hand it to the tenant over a channel you trust and do not write it to logs. The example above deliberately leaves it out.

What creating a tenant does

The call creates the tenant record and a matching MagicDoor user. If the user cannot be created — for instance because the email or phone already belongs to someone else's account — the tenant record is rolled back and nothing is left behind.

A tenant created here is a person and nothing more. They are not on any lease until they are added to one.