MagicDoorAPI
SupportOpen MagicDoor
Rental applications

Create a rental application

Opens a new draft rental application on behalf of an applicant and returns it in full. The company's questionnaire is snapshotted onto the application at this point, so later edits to the questionnaire do not change it. Requires the rental_applications:write permission.

POST
https://services.magicdoor.com/leasing/company-portal/rental-applications

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

Every field is optional — an application with no contact details at all is a valid draft.

firstNamestring

Applicant's first name. At most 250 characters.

lastNamestring

Applicant's last name. At most 250 characters.

emailstring · email

Applicant's email address. Reminder and screening emails go here, so an application without one cannot be chased.

phonestring

Applicant's phone number. Stored in normalised form.

Response

200 · The new application, in `draft` status with no decision.

idstring

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

companyIdstring

The company that owns the application.

passwordstring

The eight-character code the applicant uses, together with the application id, to open their own application on the company website. Treat it as a secret.

statusenum<string>

Where the application is in its lifecycle. It starts as draft, becomes submitted when it is submitted, and retracted when it is withdrawn.

draftsubmittedretracted
submittedAtstring · date-time

When the application was submitted, in the company's timezone. Absent while it is still a draft.

magicDoorTermsAcceptedAtstring · date-time

When the applicant accepted MagicDoor's terms, in the company's timezone. Absent until they do. Acceptance happens on the applicant's own portal, not here.

transunionTermsAcceptedAtstring · date-time

When the applicant accepted TransUnion's terms, in the company's timezone. Absent until they do. No credit or background data is pulled before this is set.

bifurcatedScreeningRequiredboolean

True when this application falls in a jurisdiction where TransUnion requires the property manager to attest separately before a criminal report may be seen.

bifurcatedScreeningAcceptedAtstring · date-time

When the property manager gave that attestation, in UTC — unlike the other timestamps on this response, this one is not converted to the company's timezone. Absent until accepted.

decisionenum<string>

The property manager's verdict. noDecision until one is set.

noDecisionapprovedrejectedignored
isQualifiedDraftboolean

True once both a first and a last name are on the application.

groupIdstring

Ties this application to its co-applicants — every application in the group shares the value. A UUID string, not a Snowflake id. Absent until a co-applicant is invited.

tenantIdstring

The tenant this application was converted into. Absent until it is converted.

leaseIdstring

The lease this application ended up on. Absent until a lease is linked.

chatIdstring

The chat thread with the applicant. Absent when no chat exists.

aiApplicationScoreinteger

Score produced by MagicDoor's AI evaluation of the application. Absent until the evaluation has run at least once.

firstNamestring

Applicant's first name.

lastNamestring

Applicant's last name.

emailstring · email

Applicant's email address. Reminder, screening-request and info-update emails all go here.

phonestring

Applicant's phone number, stored in normalised form.

permissionToTextingboolean

Whether the applicant agreed to be contacted by text message.

ssnstring

The applicant's Social Security number, digits only with no dashes. Returned in full and unmasked to any caller holding rental_applications:read. Absent when none is on file.

dateOfBirthstring · date

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

desiredMoveInDatestring · date

When the applicant would like to move in.

maritalStatusenum<string>

Marital status the applicant selected.

singlemarrieddivorcedwidowed
driversLicenseobject

Driver's licence details the applicant supplied. Absent when none are on file.

incomeInformationobject

What the applicant stated about their income. Absent when nothing was stated.

emergencyContactobject

Who to contact in an emergency. Absent when none was given.

createdstring · date-time

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

updatedstring · date-time

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

showVerificationboolean

True when the company requires screening and this applicant's identity check has not started. The property-manager UI uses it to decide whether to show the screening step.

showPaymentboolean

True when no payment record exists yet or the fee is still unpaid.

canRequestReportsboolean

True when the applicant's identity has been verified with TransUnion, which is the point at which reports may be requested.

requestApplicantCompleteScreeningReadinessobject

Whether you can ask the applicant to finish their screening, and if not, why not.

employmentEmployment[]

The applicant's employment entries, with any documents attached to each.

residentialHistoryResidentialHistory[]

The applicant's previous addresses, with landlord-verification state and any documents attached to each.

petsPet[]

Pets declared on the application.

carsCar[]

Vehicles declared on the application.

commentsComment[]

Internal notes staff have left on the application.

filesFile[]

Documents attached to the application as a whole. Documents attached to a specific employment or residential-history entry appear only inside that entry, not here.

questionsobject

The questionnaire snapshot taken when the application was created, with the applicant's answers merged in. Keyed by question category. Absent when the company has no questionnaire configured.

screeningobject

TransUnion screening state for this applicant. Absent until screening has been started or waived.

paymentobject

The application fee. Absent until a payment record exists.

reportsReport[]

Screening reports that have been unlocked for this application. Reports TransUnion delivered but which nobody unlocked are not listed.

coApplicantsCoApplicant[]

Other applications sharing this application's groupId.

interestedUnitsInterestedUnit[]

The units the applicant applied for, with the unit and property details filled in.

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

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

This response carries personal data

The rental application includes the applicant's Social Security number, date of birth, and — once screening has run — their credit score and credit utilisation. Anyone holding rental_applications:read sees all of it, unredacted. Do not log or cache this response where it is not needed, and strip these fields before passing the payload to anything that does not require them.