# Creating a Screening Group
To view the details of the request you need to send, please click the arrow in the section below.
## Create Screening Group
`POST` `https://api.payscore.com/api/v1/screening_groups`
Creates a screening group for a single applicant or multiple applicants. When an Automated Income Verification request is created successfully, an email and/or text is sent to all applicants inviting them to complete the screening.
#### Request Body
| Name | Type | Required? | Description |
| ---------------------------------------------- | ------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `applicants` | array | yes | The applicants attached to the income verification request. See `Applicant` model below. |
| `property` | object | yes | 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` | boolean | yes | Is the decision maker paying or is the applicant? |
| `decision_maker_display_name` | string | yes | The name of the decision maker to be displayed on the request. This can also be a company name. |
| `monthly_rent` | number | yes | 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. |
| `income_multiplier_threshold` **(DEPRECATED)** | number | no | 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. |
| `criteria_rule_set_id` | string | no | The ID of the criteria rule set that you would want to use on this income verification request. If left blank, the default criteria rule set will be used. |
| `webhook_url` | string | no | The URL that will receive webhook notifications for the screening group created. |
| `is_invitation_disabled` | boolean | no | If you decide to not want Payscore to invite the applicant via email and/or text, pass in `true` for this field. |
{% tabs %}
{% tab title="200 A successfully created screening group with 2 applicants attached." %}
```typescript
{
"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_name": "Test Property",
"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_expired": false,
"correlation_id": "12345"
"created_at_timestamp": 1574244834717.303
}
```
{% endtab %}
{% tab title="400 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"
]
}
```
{% endtab %}
{% endtabs %}
{% hint style="warning" %}
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.
{% endhint %}
### 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
| `name` | `string` | yes | The property's name |
| ---------------- | -------- | --- | --------------------------------------------------- |
| `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_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` **(DEPRECATED)** | `string` | The approval recommendation of the screening group. The value can be `unavailable`, `approve`, or `decline`. **This has been deprecated in favor of income criteria.** |
| `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` **(DEPRECATED)** | `number` | The income multiplier threshold that is used to calculate whether the applicant's net income to rent meets the decision maker's requirements. **This has been deprecated in favor of income criteria.** |
| `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`, `no_online_banking`, `share_bank`, `no_income`, or `bank_cannot_connect`. |
#### ScreeningStatus Values
| 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`. |
#### **ReasonCompleted Values**
| **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. After confirming they do not have a bank, our support team submits this status. |
| `no_online_banking` | The applicant has reached out to our support team that they do not have online banking. After confirming they do not have 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. |
| `missing_bank` | The applicant has reached out to our support team and their bank is not listed in our system. You can find our coverage here: |