Creating a Screening Group
Creating a screening group allows you to invite applicants by both email and/or text message to verify their income.
To view the details of the request you need to send, please click the arrow in the section below.
post
https://theclosingdocs.com/api/v1/screening_groups
Create Screening Group
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.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. |
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 |
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_name | string | The property's name for the screening |
property_street_address | string | The property's street address for the screening |
unit_number | string | The unit number 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 income verification request expired? Requests automatically expire within 14 days if not fully completed. |
is_report_expired | boolean | Is the income verification 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 , or bank_cannot_connect . |
Value | Description |
not_started | The applicant has not begun the income verification process. "Beginning the process" means clicking the link sent via email/text, and creating a password for their account. |
in_progress | The applicant has begun the income verification process but has not submitted their final report. If the applicant has connected their bank but has not submitted their report, the status is still in_progress . If the applicant re-opens their screening, the status will change from completed to in_progress . |
completed | The applicant has completed their screening. The outcome of their screening is marked in the reason_completed field of Screening . |
Value | Description |
not_completed | The applicant has not completed the screening |
finished | The applicant has completed the screening by connecting their bank account(s) and submitted the report |
no_bank | The applicant has reached out to our support team that they do not have a bank or online banking. After confirming they do not have a bank/online banking, our support team submits this status. |
share_bank | The applicant has submitted that they share a bank with another applicant. At least one applicant in the screening group will need to connect their bank and share their banking information. |
no_income | The applicant has submitted that they do not produce any income, and therefore don't need to connect a bank account. |
bank_cannot_connect | The applicant has reached out to our support team that they cannot connect their bank. After the support team has assisted them with all possible data providers and troubleshooting, if they still cannot successfully pull their bank data, the support team submits this status. |