Application screening

Request screening reports

Unlocks one or more TransUnion reports for a verified applicant and charges the company for each. Only legal once the applicant's identity has been verified. Requires the rental_applications:write permission.

POST

https://services.magicdoor.com/leasing/company-portal/rental-applications/{applicationId}/screening/reports/request

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

applicationIdstringrequired

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

example: 1830472847398404096

Body

application/json

The first request for an applicant also tells TransUnion to start producing all three reports; they arrive asynchronously, so a report often shows requested for a while before turning available.

reportTypesenum<string>[]required

Which reports to unlock. At least one. Case-insensitive. Duplicates are collapsed. A credit report must either already exist or be included here, otherwise the call is refused.

creditcriminaleviction

approvedReportsAlreadyExistsboolean

Set to true to go ahead when one of the requested reports has already been unlocked. Without it, asking for an already-unlocked report is refused so the company is not charged twice by accident.

default: false

Response

200 · The reports that were unlocked, one entry per requested type.

idstring

The report record.

reportTypeenum<string>

Which TransUnion report this is.

criminalcrediteviction

reportCulturestring

The locale the report was produced in, for example "en-US".

reportStatusenum<string>

Whether the report content has arrived from TransUnion yet. Only available reports can be read.

notRequestedrequestedavailablefailed

requestedAtstring · date-time

When the report was requested, in the company's timezone.

createdstring · date-time

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

updatedstring · date-time

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

400 · The request breaks one of the rules: no report types were given, screening has not been started, the applicant's identity is not verified, a credit report was neither requested nor already present, or a requested report is already unlocked and `approvedReportsAlreadyExists` was not set.

422 · MagicDoor cannot bill the company for the TransUnion fees. The company's invoicing setup — payment account or method, bank account, and cash chart-of-account — has to be completed first.

422 · TransUnion rejected or did not answer the request. Nothing was unlocked and the company was not charged.

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.

Screening data depends on the applicant's consent

TransUnion is only contacted after the applicant has accepted TransUnion's terms on their own portal — check transunionTermsAcceptedAt on the rental application. Until then the applicant's identity cannot be verified, no report can be produced, and screening.creditScore and screening.creditUtilization stay absent. Nothing in this section makes the applicant consent; it only acts on a consent that already exists.

This costs the company money

Each report unlocked here raises a charge against the company at the per-report fee shown by Get report availability and pricing. Charges are deduplicated per application and report type, so a retry of the same request will not bill twice.

Credit comes first

A credit report must exist, or be in the same request, before a criminal or eviction report can be unlocked. criminalPrerequisiteReports and evictionPrerequisiteReports on the capabilities endpoint tell you when that applies.