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.

Authentication

Next - Sending Income Verification Requests

Receiving Status Updates

Last updated 1 month ago

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

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`.

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.

Creating a Screening Group

postCreate Screening Group

Request Parameter Schemas

Applicant Schema

Property Schema

Response Schemas

Screening Group Schema

Screening Schema

post
Create Screening Group