Creating a Screening Group

Creating a screening group allows you to invite applicants by both email and/or text message to verify their income.

post
Create Screening Group

https://theclosingdocs.com/api/v1/screening_groups
Creates a screening group for a single applicant or multiple applicants. When an Automated Income Verification (AIV) screening request is created successfully, an email and/or text is sent to all applicants inviting them to complete the screening.
Request
Response
Request
Body Parameters
applicants
required
array
The applicants attached to the income verification request. See Applicant model below.
property
required
object
The property's address that will be displayed in the screening workflow to let the applicant know they are in the right place. See Property model below.
is_decision_maker_paying
required
boolean
Is the decision maker paying or is the applicant?
decision_maker_display_name
required
string
The name of the decision maker to be displayed on the request. This can also be a company name.
monthly_rent
optional
number
The monthly rent in dollars is used to calculate the net income to rent multiplier. If there are multiple applicants, this is the monthly rent of the entire household. If left blank, then the multiplier will not be calculated.
income_multiplier_threshold
optional
number
The income multiplier threshold that is used to determine whether the applicant meets the net income to rent threshold. For example, if the decision maker wants 3.0x the net income to rent ratio, you would send 3.0 for this income verification request. If left blank, the default value is 2.5x.
correlation_id
optional
string
A unique identifier that will be saved with the screening group. This is generally used to correlate to another ID in your database.
webhook_url
optional
string
The URL that will receive webhook notifications for the screening group created.
Response
200: OK
A successfully created screening group with 2 applicants attached.
{
"id": "905963d4-0649-4046-8f39-7997a9e45ed4",
"screenings": [{
"id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
"applicant_first_name": "John",
"applicant_last_name": "Smith",
"applicant_email": "johnsmith@gmail.com",
"reason_completed": "not_completed",
"screening_status": "not_started"
}, {
"id": "13cc2254-152e-4e78-937c-66b7d89c65a2",
"applicant_first_name": "Bob",
"applicant_last_name": "Thomas",
"applicant_email": "bobthomas@gmail.com",
"reason_completed": "finished",
"screening_status": "completed"
}],
"status": "in_progress",
"approval_recommendation": "unavailable",
"property_street_address": "1234 Pike St. #101",
"income_multiplier_threshold": 2.5,
"monthly_rent_cents": 200000,
"is_decision_maker_paying": true,
"is_report_expired": false,
"is_report_expired": null,
"created_at_timestamp": 1574244834717.303
}
400: Bad Request
If you are missing parameters or the applicants' emails are invalid, you will receive a 400 Bad Request with the errors in this format.
{
"errors": [
"invalidemail@gmail.com is an invalid email",
"invalidemail2@gmail.com is an invalid email"
]
}

In our production environment, we will validate whether the applicants' emails are valid and exist to prevent typos. If the email does not exist, you will receive a 400 Bad Request. An example of the error response can be seen in the Response tab above.

Request Parameter Schemas

Applicant Schema

Field

Type

Required?

Description

applicant_first_name

string

yes

The applicant's first name

applicant_last_name

string

yes

The applicant's last name

applicant_email

string

yes

The applicant's email. This is the email address where we will send the AIV invitation

applicant_phone_number

string

no

The applicant's phone number, including the international code (ex. +19842342345). Including this will send a text message AIV request as well as an email.

Property Schema

Field

Type

Required?

Description

street_address

string

yes

The property's street address

city

string

yes

The property's city

state

string

yes

The property's state fully spelled out. No initials

zip_code

string

yes

The property's zip code

unit

string

no

The property's unit number, if available

Response Schemas

Screening Group Schema

Field

Type

Description

id

string

The unique id of the screening group

screenings

Screening[]

The individual AIV screenings that make up the screening group

status

string

The status of the entire screening group. The value can be not_started, in_progress, or completed.

property_street_address

string

The property's street address for the screening

monthly_rent_cents

number

The monthly rent in cents

approval_recommendation

string

The approval recommendation of the screening group. The value can be unavailable, approve, or decline.

is_decision_maker_paying

boolean

Is the decision maker paying or is the applicant?

is_expired

boolean

Has the AIV request expired? Requests automatically expire within 14 days if not fully completed.

is_report_expired

boolean

Is the AIV report expired for this screening group? If the report doesn't exist, this value is false.

decision_maker_display_name

string

The name of the decision maker to be displayed on the screening. This can also be a company name.

income_multiplier_threshold

number

The income multiplier threshold that is used to calculate whether the applicant's net income to rent meets the decision maker's requirements.

correlation_id

string

A unique identifier that will be saved with the screening group. This is generally used to correlate to another ID in your database.

created_at_timestamp

number

UNIX timestamp of when the AIV request was created

Screening Schema

Field

Type

Description

id

string

The unique ID of the screening

applicant_first_name

string

The applicant's first name

applicant_last_name

string

The applicant's last name

applicant_email

string

The applicant's email

screening_status

string

The status of the individual screening. The value can be not_started, in_progress, or completed.

reason_completed

string

How the screening was completed. Values can be not_completed, finished, no_bank, share_bank, no_income, no_bank, or bank_cannot_connect.