# Introduction

Payscore's API allows you to send an automated income verification request to a user, securely verifying their income.

## Getting Started

Every network request should be sent with the following headers:

| **Header**     | **Value**          |
| -------------- | ------------------ |
| `Accept`       | `application/json` |
| `Content-Type` | `application/json` |

### Environments

Payscore provides two environments: staging and production. The staging environment uses the following url:

```ruby
https://api.staging.payscore.com
```

Use the staging environment for development, as no charges will occur. For access to the staging environment, reach out to <support@payscore.com> and you will be provided a login.

The production environment is where all live production traffic should take place. Once you’re ready to gain production access, reach out to our team and we’ll provide you with a production login. Our production environment uses the following url:

```ruby
https://api.payscore.com
```


# Authentication

In order to authenticate your network requests to Payscore, you are required to attach an access token to every request.

## Get Access Token

<mark style="color:green;">`POST`</mark> `https://api.payscore.com/api/v1/tenants/auth`

Request to get your API access token, which expires in 30 minutes. The access token will be returned in the `Authorization` header.

#### Request Body

| Name        | Type   | Description     |
| ----------- | ------ | --------------- |
| client\_id  | string | Your client ID  |
| secret\_key | string | Your secret key |

{% tabs %}
{% tab title="204 " %}

```
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIwMDAwMDAwMC0wM...
```

{% endtab %}
{% endtabs %}


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

## Create Screening Group

<mark style="color:green;">`POST`</mark> `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: <https://app.payscore.com/coverage>                                                                                                                   |


# Receiving Status Updates

Once you've sent out an income verification request, you will need to see the status of the update in order to see if the applicant has completed the verification.

We have two ways you can get the status of the income verification request sent. The first way is that you can fetch the screening group using the following endpoint:

## Get Screening Group

<mark style="color:blue;">`GET`</mark> `https://api.payscore.com/api/v1/screening_groups/{id}`

Get the screening group entity via ID.

#### Path Parameters

| Name | Type   | Description                               |
| ---- | ------ | ----------------------------------------- |
| id   | string | The ID of the screening group to retrieve |

{% tabs %}
{% tab title="200 " %}

```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.",
    "unit_number": "#101",
    "monthly_rent_cents": 200000,
    "is_decision_maker_paying": true,
    "is_report_expired": false,
    "is_report_expired": null,
    "created_at_timestamp": 1574244834717.303
}
```

{% endtab %}
{% endtabs %}

This endpoint will get you the status of the entire screening group and each individual screening.

For screenings in a group, the applicant can state that they share a bank with another applicant, or produces no income. You will not be charged in these scenarios, and the screening will be marked as completed.

The second way to get the status of an income verification request is that you receive real-time screening updates from a webhook sent to a url of your choice.


# Webhooks

You can receive real-time status updates of your income verification requests by using webhooks.

You can receive notifications from Payscore via webhooks when the following occurs:

* When an applicant has begun an income verification request
* When an applicant successfully completes an income verification request
* When a screening group is completed successfully
* When an applicant's bank is not supported
* When an applicant does not have a bank
* When an applicant does not have online banking
* When an applicant cannot connect their bank
* When an applicant states that they share a bank, or do not produce any income
  * This is only for income verification requests with multiple applicants'
* When an applicant re-opens their screening to modify the information
* When an income verification report is 2 days from expiring
* When an income verification report has expired
* When an incomplete income verification request has expired
* When an applicant is added to a screening group
* When an applicant is removed from a screening group

The webhook will be sent as a `POST` request to the `webhook_url` attribute of the screening group you created.

### `BEGIN_SCREENING`

Payscore fires the `BEGIN_SCREENING` webhook when an applicant signs up and begins the income verification request.

Example:

```
{
    "code": "BEGIN_SCREENING",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
```

### `SCREENING_COMPLETED`

Once the applicant finishes an income verification process, the `SCREENING_COMPLETED` webhook will fire. Note that this event fires when an individual income screening is completed, not the entire screening group.

Example:

```
{
    "code": "SCREENING_COMPLETED",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
```

### `SCREENING_GROUP_COMPLETED`

Once every applicant from the screening group has completed their income verification request, the `SCREENING_GROUP_COMPLETED` webhook will fire. This means that the income verification report has been generated and is ready to be presented.

{% hint style="warning" %}
This webhook might fire several times due to an applicant re-opening their screening in order to add/remove an account or modify their explanation. Be sure to update your report whenever this webhook fires in order to show the most updated income report.
{% endhint %}

Example:

```
{
    "code": "SCREENING_GROUP_COMPLETED",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
```

### `BANK_NOT_SUPPORTED`

If the applicant's bank is not supported, the `BANK_NOT_SUPPORTED` webhook will fire. The applicant's bank will be in the value property.

Example:

```
{
    "code": "BANK_NOT_SUPPORTED",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
    "value": "Small Alaskan Credit Union"
}
```

### `NO_ONLINE_BANKING`

If the applicant does not use online banking, the `NO_ONLINE_BANKING` webhook will fire. The applicant's bank will be in the value property.

Example:

```
{
    "code": "NO_ONLINE_BANKING",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
    "value": "Small Alaskan Credit Union"
}
```

### `NO_BANK`

If the applicant does not have a bank, the `NO_BANK` webhook will fire.

Example:

```
{
    "code": "NO_BANK",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
```

### `BANK_CANNOT_CONNECT`

If the applicant's bank cannot connect due to technical errors, the `BANK_CANNOT_CONNECT` webhook will fire. The applicant's bank will be in the value property.

Example:

```
{
    "code": "BANK_CANNOT_CONNECT",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
    "value": "Small Alaskan Credit Union"
}
```

### **`SHARE_BANK`**

If the applicant states that they share a bank with another applicant, the `SHARE_BANK` webhook will fire. This only occurs with screening groups with more than 1 applicant. \
\
Example:

```
{
    "code": "SHARE_BANK",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
```

### `NO_INCOME`

If the applicant states that they produce no income, the `NO_INCOME` webhook will fire. This only occurs with screening groups with more than 1 applicant.

Example:

```
{
    "code": "NO_INCOME",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
```

### `RE_OPEN_SCREENING`

If the applicant decides to re-open their screening request because they want to add or remove accounts or modify their income explanation, this webhook will fire. In this case, you will want to update the screening status back to `In Progress` on your end until the `SCREENING_COMPLETED` webhook fires again.

Example:

```
{
    "code": "RE_OPEN_SCREENING",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
```

### **`REPORT_SOON_TO_EXPIRE`**

Our reports expire in 14 days in order to remain FCRA compliant. Two days before the report expires, we will send a webhook providing the following notice: `REPORT_SOON_TO_EXPIRE`.

Example:

```
{
    "code": "REPORT_SOON_TO_EXPIRE",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
```

### **`REPORT_EXPIRED`**

Our reports expire in 14 days in order to remain FCRA compliant. Once the report expires, we will send a webhook providing the following notice: `REPORT_EXPIRED`.

Example:

```
{
    "code": "REPORT_EXPIRED",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
```

### **`INVITE_EXPIRED`**

If an invite has not been completed within 14 days, the invite expires for the applicant. When this happens, a webhook with the `INVITE_EXPIRED` event will be sent, which includes the `screening_id` of the incomplete screening that expired.

Example:

```
{
    "code": "INVITE_EXPIRED",
    "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562"
}
```

### **`APPLICANT_ADDED`**

If an applicant is added to a screening group after it has been created, the `APPLICANT_ADDED` webhook will fire. The added applicant’s first name, last name, email address and phone number will be in the value property. Note that the phone number field may be null if no applicant phone number is provided.

Example:

```
{
 "code": "APPLICANT_ADDED",
 "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
 "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
 "value": {
  "applicant_first_name": "John",
  "applicant_last_name": "Smith",
  "applicant_email": "john@gmail.com",
  "applicant_phone_number": "+18001234567"
 }
}
```

### **`APPLICANT_REMOVED`**

If an applicant is removed from a screening group after it has been created, the `APPLICANT_REMOVED` webhook will fire. The removed applicant’s first name, last name, email address and phone number will be in the value property. Note that the phone number field may be null if no applicant phone number is provided.

Example:

```
{
 "code": "APPLICANT_REMOVED",
 "screening_group_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
 "screening_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
 "value": {
  "applicant_first_name": "John",
  "applicant_last_name": "Smith",
  "applicant_email": "john@gmail.com",
  "applicant_phone_number": "+18001234567"
 }
}
```

### Validating Webhooks

When a webhook is sent, Payscore uses the webhook body and your secret key to create a hash signature, which is sent in the header `Verification-Signature`. The hash is created using HMAC-SHA256 and is hex encoded.&#x20;

In order for you to validate that the webhook is legitimate, hash the raw webhook body using your secret key as the key, and then compare your generated signature with the `Verification-Signature`  header value.

{% hint style="warning" %}
**Do Not Parse or Cast the Webhook Request Body**\
While generating the signature at your end, ensure that the webhook body passed as an argument is the raw webhook request body. Do not parse or cast the webhook request body.
{% endhint %}


# Resend Screening Request Notification

You can resend the initial email/text notification to the applicant by hitting this endpoint. This is useful when the applicant cannot find the initial invite.

You can resend the income verification request email and text (if included) by hitting the following endpoint. This will resend the notification inviting the applicant to complete the income verification request for every incomplete screening in the screening group. This will not resend the notification for completed screenings in the screening group.

## Resend Screening Request Notification

<mark style="color:green;">`POST`</mark> `https://api.payscore.com/api/v1/screening_groups/{id}/send_notification`

Resend the initial email/text notification to the screening group.

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | The ID of the screening group |

{% tabs %}
{% tab title="204 When the notification has been resent successfully" %}

```
```

{% endtab %}
{% endtabs %}

<br>


# Force-Complete a Screening Group Request

You can force-complete a screening group to produce a grouped report without having all the applicants complete the income screening.

Screening group requests with more than 1 applicant require all applicants to complete the income verification process in order to produce the report. This is because we need all of the applicants' income data to produce the aggregated report.

However, if for whatever reason you require the report to produced immediately, you can "force-complete" a screening group request by hitting the endpoint below. The applicants that have not completed their screening will also receive an email/text notification that their screening has been cancelled.

Be aware that if no applicants have completed the screening yet (or if they have completed the screening but submitted that they share a bank or produce no income), the report will look fairly blank.

{% hint style="info" %}
This is an **asynchronous** operation, so once you hit this endpoint, wait for the \
`SCREENING_GROUP_COMPLETED`webhook to fire before pulling the report.
{% endhint %}

{% hint style="warning" %}
This endpoint is only available for screening group requests with more than 1 applicant.
{% endhint %}

## Force-Complete a Screening Group

<mark style="color:green;">`POST`</mark> `https://api.payscore.com/api/v1/screening_groups/{id}/complete`

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | The ID of the screening group |

{% tabs %}
{% tab title="204 When the screening group has been completed and the report has begun to be produced." %}

```
```

{% endtab %}

{% tab title="400 When the screening group has only 1 screening. This operation is only available for a screening group with multiple screenings." %}

```
```

{% endtab %}
{% endtabs %}


# Get All Screening Groups

You can get all screening groups paginated with the following route:

## Get Screening Groups

<mark style="color:blue;">`GET`</mark> `https://api.payscore.com/api/v1/screening_groups`

Get all screening groups paginated

#### Query Parameters

| Name | Type   | Description                                                                                  |
| ---- | ------ | -------------------------------------------------------------------------------------------- |
| page | String | The page of all entities you want to pul. The number of records returned in each page is 25. |

{% tabs %}
{% tab title="200 " %}

```typescript
{
    "screening_groups": [{
        "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.",
        "unit_number": "#101",
        "monthly_rent_cents": 200000,
        "is_decision_maker_paying": true,
        "is_report_expired": false,
        "is_report_expired": null,
        "created_at_timestamp": 1574244834717.303
    },
    "total_count": 1
}
```

{% endtab %}
{% endtabs %}


# Delete a Screening Group

Deleting a screening group allows you to cancel an income verification request that has not been completed yet.

If you accidentally mistyped an applicant's email or decide to cancel their income verification request, you can delete the screening group, preventing the applicant from completing the income verification request.

Once you delete the screening group, all applicants are notified by email and/or text that their income verification request has been cancelled and no further action is needed.

{% hint style="warning" %}
You can only delete a screening group if no applicants have completed their request. If an applicant has completed their income verification request, you will be unable to delete the screening group and will receive a `409 Conflict` error.
{% endhint %}

## Delete a Screening Group

<mark style="color:red;">`DELETE`</mark> `https://api.payscore.com/api/v1/screening_groups/{id}`

Delete a screening group

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | The ID of the screening group |

{% tabs %}
{% tab title="204 When the screening group has been deleted successfully" %}

```
```

{% endtab %}

{% tab title="409 If the screening group has a completed screening" %}

```
```

{% endtab %}
{% endtabs %}


# Getting the Report Url

You can obtain the completed income report's URL by hitting this endpoint.

When the screening group is completed, we will produce and host a pdf report. You can get the url to that report by hitting the following endpoint. For security, this returned url expires in 2 hours. We recommend generating this url and redirecting on demand (when the user clicks to view the income report).

If the screening group is still in progress and the report has not been created yet, the response will have a status code of `404 Not Found`. If the report has expired, the response will have a status code of `410 Gone`.

## Get Report PDF URL

<mark style="color:blue;">`GET`</mark> `https://api.payscore.com/api/v1/screening_groups/{id}/report`

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | The ID of the screening group |

{% tabs %}
{% tab title="200 The response for a successfully completed income verification report" %}

```
{
    "url": "https://closing-docs.s3.us-west-2.amazonaws.com/prod/scr..."
}
```

{% endtab %}

{% tab title="404 The response if the report has not been created yet" %}

```
```

{% endtab %}

{% tab title="410 The response if the report has expired" %}

```
```

{% endtab %}
{% endtabs %}


# Getting the Report Data

When the report is ready, you can get the report in json format by hitting the following endpoint.

When the screening group is completed, we will provide the data used to populate our report in JSON format.

If the screening group is still in progress and the report has not been created yet, the response will have a status code of `404 Not Found`. If the report has expired, the response will have a status code of `410 Gone`.

Note that the schemas for an individual income report and an income report with multiple applicants differ. The main difference is that the combined income report has an array of individual screenings.

## Get Report JSON Data

<mark style="color:blue;">`GET`</mark> `https://api.payscore.com/api/v1/screening_groups/{id}/report/data`

#### Path Parameters

| Name | Type   | Description                   |
| ---- | ------ | ----------------------------- |
| id   | string | The ID of the screening group |

{% tabs %}
{% tab title="200 The response for a successfully completed individual income verification report" %}

```
{
    "total_net_income": 280000,
    "two_month_avg_monthly_net_income": 35000,
    "three_month_avg_monthly_net_income": 35000,
    "six_month_avg_monthly_net_income": 35000,
    "nine_month_avg_monthly_net_income": null,
    "twelve_month_avg_monthly_net_income": null,
    "total_non_recurring_deposits": 60340,
    "summary_timespan_length": 239,
    "bank_connections": [
        {
            "accounts": [
                {
                    "name": "Dag Credit Card",
                    "type": "Credit",
                    "available_balance": null,
                    "current_balance": null
                },
                {
                    "name": "Saving Plus",
                    "type": "Savings",
                    "available_balance": 10500,
                    "current_balance": 30500
                },
                {
                    "name": "Checking Account",
                    "type": "Checking",
                    "available_balance": 150000,
                    "current_balance": 160000
                }
            ],
            "income": {
                "total_net_income": 420000,
                "two_month_avg_monthly_net_income": 35000,
                "three_month_avg_monthly_net_income": 35000,
                "six_month_avg_monthly_net_income": 35000,
                "nine_month_avg_monthly_net_income": 35000,
                "twelve_month_avg_monthly_net_income": null,
                "total_non_recurring_deposits": 35000,
                "income_streams": [
                    {
                        "name": "The Closing Docs Payroll",
                        "transactions": [
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "04/01/2020"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "03/01/2020"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "02/01/2020"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "01/01/2020"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "12/01/2019"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "11/01/2019"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "10/01/2019"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "09/01/2019"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "08/01/2019"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "07/01/2019"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "06/01/2019"
                            },
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Payroll",
                                "date": "05/01/2019"
                            }
                        ],
                        "monthly_income": 34375,
                        "start_date": "05/01/2019",
                        "end_date": "04/01/2020"
                    }
                ],
                "non_recurring_deposit_streams": [
                    {
                        "name": "The Closing Docs Irregular Income",
                        "transactions": [
                            {
                                "amount": 35000,
                                "name": "The Closing Docs Irregular Income",
                                "date": "04/01/2020"
                            }
                        ]
                    }
                ],
                "start_date": "05/01/2019",
                "end_date": "04/01/2020",
                "transaction_timespan_length": 336
            },
            "institution_name": "Chase"
        },
        {
            "accounts": [
                {
                    "name": "Checking",
                    "type": "Checking",
                    "available_balance": 100000,
                    "current_balance": 100000
                },
                {
                    "name": "Credit Card",
                    "type": "Credit Card",
                    "available_balance": 100000,
                    "current_balance": 100000
                },
                {
                    "name": "Loan",
                    "type": "Loan",
                    "available_balance": 100000,
                    "current_balance": 100000
                },
                {
                    "name": "Savings",
                    "type": "Savings",
                    "available_balance": 100000,
                    "current_balance": 100000
                }
            ],
            "income": {
                "total_net_income": 0,
                "two_month_avg_monthly_net_income": 0,
                "three_month_avg_monthly_net_income": 0,
                "six_month_avg_monthly_net_income": 0,
                "nine_month_avg_monthly_net_income": null,
                "twelve_month_avg_monthly_net_income": null,
                "total_non_recurring_deposits": 25340,
                "income_streams": [],
                "non_recurring_deposit_streams": [
                    {
                        "name": "Paycheck",
                        "transactions": [
                            {
                                "amount": 5208,
                                "name": "Paycheck",
                                "date": "02/09/2020"
                            },
                            {
                                "amount": 6505,
                                "name": "Paycheck",
                                "date": "02/01/2020"
                            },
                            {
                                "amount": 6547,
                                "name": "Paycheck",
                                "date": "01/05/2020"
                            },
                            {
                                "amount": 7080,
                                "name": "Paycheck",
                                "date": "12/31/2019"
                            }
                        ]
                    }
                ],
                "start_date": "08/14/2019",
                "end_date": "04/09/2020",
                "transaction_timespan_length": 239
            },
            "institution_name": "Wells Fargo"
        }
    ],
    "identity": {
        "full_name": "Bob Smith",
        "email": "bob@gmail.com"
    },
    "income_explanation": "This is an income explanation",
    "reason_completed": "finished",
    "created_at": "04/10/2020"
}
```

{% endtab %}

{% tab title="404 The response if the report has not been created yet" %}

```
```

{% endtab %}

{% tab title="410 The response if the report has expired" %}

```
```

{% endtab %}
{% endtabs %}

### Response Schema

#### IndividualReport Schema

| Field                                          | Type                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `screening_id`                                 | `string`                 | The `Screening` that this `IndividualReport` corresponds with                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `recurring`                                    | `IncomeData`             | The income data for all the recurring income from the report's bank connections, not including the`income_streams` attribute. The timespan of these metrics are `summary_timespan_length`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `non_recurring`                                | `IncomeData`             | The income data for all the non-recurring income from the report's bank connections, not including the `income_streams` attribute. The timespan of these metrics are `summary_timespan_length`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `summary_timespan_length`                      | `number`                 | The timespan length in days that the recurring and non-recurring `IncomeData` metrics cover, starting from the date the report was created. This is the minimum timespan length between `bank_connnections`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `identity`                                     | `Identity`               | The applicant's identity information                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `bank_connections`                             | `BankConnection[]`       | The banks that the applicant has added onto the income verification request                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `income_explanation`                           | `string`                 | An explanation given by the applicant that is used to bring context to their income summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `reason_completed`                             | `string`                 | The reason the screening was completed. If this is a report with a single applicant, the value will either be `finished`, `no_bank`, `no_online_banking`, `missing_bank`, or `bank_cannot_connect`. If this is part of a report with multiple applicants, the value can also be `share_bank`, or `no_income`.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `income_multiplier`                            | `number \| null`         | <p>The net income to rent multiplier of the applicant. This is calculated by comparing the applicant's <strong>recurring 3 month average monthly net income</strong> with the monthly rent. When this value is not available (when the <code>summary\_timespan\_length</code><80 days), we use the <strong>recurring 2 month average monthly net income</strong>.</p><p></p><p>When the 2 month average monthly value is not available (<code>summary\_timespan\_length</code> is <50 days), then this value is null, and we do not calculate the income to rent multiplier since we do not have enough data to confidently provide a multiplier. This value is also null when a <code>monthly\_rent</code> is not provided when creating the screening request.</p> |
| `income_multiplier_threshold` **(DEPRECATED)** | `number \| null`         | The income multiplier threshold that was used when creating a screening request. The default value is 2.5x.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `income_multiplier_result` **(DEPRECATED)**    | `string \| null`         | The `income_multplier` compared to the `income_multiplier_threshold`. Values can be `above`, `below`, or `equal`. This value is null when the income multiplier is null.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `income_criteria_results`                      | `IncomeCriteriaResult[]` | <p>The calculated results per each income criteria that your organization has configured.<br><br>If this is set, <code>income\_multiplier\_result</code> will be <code>"unavailable"</code> and <code>income\_multiplier</code> will be <code>null.</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `property_monthly_rent`                        | `number`                 | The monthly rent of the property in cents                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `created_at`                                   | `string`                 | The date the report was created at. Formatted “08/25/2019”.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

The `IndividualReport` schema comprises of an income summary for all the bank connections that the applicant has attached to their income verification request.&#x20;

{% hint style="info" %}
The most important thing to note is that the `summary_timespan_length` is the minimum timespan of all the bank connections attached to the request. This is also the timespan that is used to calculate the recurring and non-recurring `IncomeData` metrics. The reason we do this is because not all financial institutions provide the same amount data history. Most institutions provide 12 months, but some provide only 6 months or even 3 months of data history. Therefore, in order to provide the most accurate information, we can only confidently compute the total and monthly average income based on the banks' shortest timespans.
{% endhint %}

#### IncomeData Schema

| Field                      | Type                           | Description                                                                                                                                                            |
| -------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total`                    | `number`                       | The total amount of income in cents received by the applicant(s) over a timespan, starting from the date the report was created.                                       |
| `two_month_avg_monthly`    | `number \| null`               | The average amount of income per month in cents the applicant(s) have received in the past 2 months. This value will be `null` if the timespan is less than 50 days.   |
| `three_month_avg_monthly`  | `number \| null`               | The average amount of income per month in cents the applicant(s) have received in the past 3 months. This value will be `null` if the timespan is less than 80 days.   |
| `six_month_avg_monthly`    | `number \| null`               | The average amount of income per month in cents the applicant(s) have received in the past 6 months.This value will be `null` if the timespan is less than 170 days.   |
| `nine_month_avg_monthly`   | `number \| null`               | The average amount of income per month in cents the applicant(s) have received in the past 9 months.This value will be `null` if the timespan is less than 260 days.   |
| `twelve_month_avg_monthly` | `number \| null`               | The average amount of income per month in cents the applicant(s) have received in the past 12 months. This value will be `null` if the timespan is less than 350 days. |
| `income_streams`           | `IncomeStream [] \| undefined` | A list of the applicant's deposit streams. This attribute is only present for a `bank_connection`'s recurring and non-recurring income data.                           |

#### Identity Schema

| Field       | Type     | Description               |
| ----------- | -------- | ------------------------- |
| `full_name` | `string` | The applicant's full name |
| `email`     | `string` | The applicant's email     |

#### BankConnection Schema

| Field              | Type            | Description                               |
| ------------------ | --------------- | ----------------------------------------- |
| `income`           | `IncomeSummary` | The income summary for the connected bank |
| `accounts`         | `Account[]`     | The accounts for the connected bank       |
| `institution_name` | `string`        | The name of the institution               |

#### IncomeSummary Schema

| Field                         | Type         | Description                                                                                                                                                                                          |
| ----------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recurring`                   | `IncomeData` | The income data for all the recurring income from the bank connection. The timespan of these metrics are `transaction_timespan_length`.                                                              |
| `non_recurring`               | `IncomeData` | The income data for all the non-recurring income from the bank connection. The timespan of these metrics are `transaction_timespan_length`.                                                          |
| `start_date`                  | `string`     | The beginning date of the time period the income summary covers. Formatted “08/25/2019”.                                                                                                             |
| `end_date`                    | `string`     | The end date of the time period the income summary covers. Formatted “08/25/2020”.                                                                                                                   |
| `transaction_timespan_length` | `number`     | The timespan length in days of the transaction history pulled, starting from the date the report was created. This can also be thought of as the number of days between `start_date` and `end_date`. |

#### IncomeStream Schema

| Field                               | Type            | Description                                                                                                                                                                        |
| ----------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                              | `string`        | The name of the income stream. This is determined by the transaction's description from the bank.                                                                                  |
| `total`                             | `number`        | The total amount of income from the income stream in cents                                                                                                                         |
| `monthly_income`                    | `number`        | The monthly income of the income stream in cents                                                                                                                                   |
| `start_date`                        | `string`        | The start date of the income stream. Formatted “08/25/2019”.                                                                                                                       |
| `end_date`                          | `string`        | The end date of the income stream. Formatted “08/25/2020”.                                                                                                                         |
| `transactions`                      | `Transaction[]` | A list of the transactions that make up the income stream                                                                                                                          |
| `pay_gap_after_transaction_indexes` | `number[]`      | A list of indexes starting at `0` where there is a pay gap between deposits in the income stream. For example, an index of `3` represents a pay gap after the **4th** transaction. |

#### Transaction Schema

| Field    | Type     | Description                                      |
| -------- | -------- | ------------------------------------------------ |
| `name`   | `string` | The name of the deposit                          |
| `amount` | `number` | The amount of the deposit in cents               |
| `date`   | `string` | The date of the deposit. Formatted “08/25/2019”. |

#### Account Schema

| Field                      | Type               | Description                                                                                                                                                                                                                                                                                                                                     |
| -------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                     | `string`           | The name of the applicant’s account, assigned by the user or the financial institution                                                                                                                                                                                                                                                          |
| `type`                     | `string`           | The type of account. For example, Checking, or Savings                                                                                                                                                                                                                                                                                          |
| `current_balance`          | `number`           | The current balance of the account in cents                                                                                                                                                                                                                                                                                                     |
| `available_balance`        | `number \| null`   | The available balance of the account, in cents. When the institution does not support `available_balance`, the value will be `null`. To learn what the difference between current and available balance, click [here](https://www.quora.com/What-is-the-difference-between-current-balance-and-available-balance).                              |
| `average_balance`          | `number \| null`   | The average balance of the account for the past 6 months, in cents. When the institution does not support `average_balance`, the value will be `null`.                                                                                                                                                                                          |
| `holder_names`             | `string[] \| null` | The verified account holder names given by the institution. This can either be the holder's first name, last name or full name based on the institution. If the account is a joint account with multiple holders, we will return all of the owners in an array. When the institution does not support `holder_names`, the value will be `null`. |
| `holder_name (DEPRECATED)` | `string \| null`   | The verified account holder's name given by the institution. This can either be the holder's first name, last name or full name based on the institution. When the institution does not support `holder_name`, the value will be `null`.                                                                                                        |

#### Sample IndividualReport response

```
{
    "screening_id": "9314c3u2-8904-4eea-b947-17df724f9382",
    "identity": {
        "full_name": "John Smith",
        "email": "john@gmail.com"
    },
    "reason_completed": "finished",
    "income_multiplier_threshold": 2.5,
    "income_multiplier": 2.6,
    "income_multiplier_result": "above",
    "income_criteria_results": null,
    "created_at": "04/11/2020",
    "recurring": {
        "total": 600000,
        "two_month_avg_monthly": 50000,
        "three_month_avg_monthly": 50000,
        "six_month_avg_monthly": 50000,
        "nine_month_avg_monthly": 50000,
        "twelve_month_avg_monthly": 50000
    },
    "non_recurring": {
        "total": 0,
        "two_month_avg_monthly": 0,
        "three_month_avg_monthly": 0,
        "six_month_avg_monthly": 0,
        "nine_month_avg_monthly": 0,
        "twelve_month_avg_monthly": 0
    },
    "summary_timespan_length": 361,
    "bank_connections": [
        {
            "accounts": [
                {
                    "name": "Checking",
                    "type": "Checking",
                    "available_balance": 10000,
                    "current_balance": 11000
                },
                {
                    "name": "Saving",
                    "type": "Savings",
                    "available_balance": 20000,
                    "current_balance": 21000
                }
            ],
            "income": {
                "recurring": {
                    "total": 600000,
                    "two_month_avg_monthly": 50000,
                    "three_month_avg_monthly": 50000,
                    "six_month_avg_monthly": 50000,
                    "nine_month_avg_monthly": 50000,
                    "twelve_month_avg_monthly": 50000,
                    "income_streams": [
                    {
                        "name": "United Airlines",
                        "transactions": [
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "03/14/2020"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "02/13/2020"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "01/14/2020"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "12/15/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "11/15/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "10/16/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "09/16/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "08/17/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "07/18/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "06/18/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "05/19/2019"
                            },
                            {
                                "amount": 50000,
                                "name": "United Airlines",
                                "date": "04/19/2019"
                            }
                        ],
                        "monthly_income": 50000,
                        "start_date": "04/19/2019",
                        "end_date": "03/14/2020"
                    }]
                },
                "non_recurring": {
                    "total": 0,
                    "two_month_avg_monthly": 0,
                    "three_month_avg_monthly": 0,
                    "six_month_avg_monthly": 0,
                    "nine_month_avg_monthly": 0,
                    "twelve_month_avg_monthly": 0,
                    "income_streams": []
                },
                "start_date": "04/16/2019",
                "end_date": "04/11/2020",
                "transaction_timespan_length": 361
            },
            "institution_name": "Wells Fargo"
        }
    ],
    "income_explanation": null
}
```

### Combined Report JSON Data

The JSON schema for combined reports, or reports with multiple applicants, differs slightly by having the `reports` field comprise of the individual applicant reports.

{% hint style="warning" %}
In a combined report, if the `IndividualReport` has a `reason_completed` other than `finished`, the only fields that will be present in the `IndividualReport` response will be `screening_id`, `identity`, `reason_completed` and `created_at`.
{% endhint %}

#### CombinedReport Schema

<pre><code><strong>{
</strong><strong>    "reports": [
</strong>        {
            "screening_id": "2714c767-8904-4eea-b947-17df724f93ed",
            "identity": {
                "full_name": "Bob Smith",
                "email": "bob@gmail.com"
            },
            "reason_completed": "share_bank",
            "created_at": "04/11/2020"
        },
        {
            "screening_id": "9314c3u2-8904-4eea-b947-17df724f9382",
            "identity": {
                "full_name": "John Smith",
                "email": "john@gmail.com"
            },
            "reason_completed": "finished",
            "created_at": "04/11/2020",
            "recurring": {
                "total": 600000,
                "two_month_avg_monthly": 50000,
                "three_month_avg_monthly": 50000,
                "six_month_avg_monthly": 50000,
                "nine_month_avg_monthly": 50000,
                "twelve_month_avg_monthly": 50000
            },
            "non_recurring": {
                "total": 0,
                "two_month_avg_monthly": 0,
                "three_month_avg_monthly": 0,
                "six_month_avg_monthly": 0,
                "nine_month_avg_monthly": 0,
                "twelve_month_avg_monthly": 0
            },
            "summary_timespan_length": 361,
            "bank_connections": [
                {
                    "accounts": [
                        {
                            "name": "Checking",
                            "type": "Checking",
                            "available_balance": 10000,
                            "current_balance": 11000
                        },
                        {
                            "name": "Saving",
                            "type": "Savings",
                            "available_balance": 20000,
                            "current_balance": 21000
                        }
                    ],
                    "income": {
                        "recurring": {
                            "total": 600000,
                            "two_month_avg_monthly": 50000,
                            "three_month_avg_monthly": 50000,
                            "six_month_avg_monthly": 50000,
                            "nine_month_avg_monthly": 50000,
                            "twelve_month_avg_monthly": 50000,
                            "income_streams": [
                            {
                                "name": "United Airlines",
                                "transactions": [
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "03/14/2020"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "02/13/2020"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "01/14/2020"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "12/15/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "11/15/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "10/16/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "09/16/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "08/17/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "07/18/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "06/18/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "05/19/2019"
                                    },
                                    {
                                        "amount": 50000,
                                        "name": "United Airlines",
                                        "date": "04/19/2019"
                                    }
                                ],
                                "monthly_income": 50000,
                                "start_date": "04/19/2019",
                                "end_date": "03/14/2020"
                            }]
                        },
                        "non_recurring": {
                            "total": 0,
                            "two_month_avg_monthly": 0,
                            "three_month_avg_monthly": 0,
                            "six_month_avg_monthly": 0,
                            "nine_month_avg_monthly": 0,
                            "twelve_month_avg_monthly": 0,
                            "income_streams": []
                        },
                        "start_date": "04/16/2019",
                        "end_date": "04/11/2020",
                        "transaction_timespan_length": 361
                    },
                    "institution_name": "Wells Fargo"
                }
            ],
            "income_explanation": null
        }
    ],
    "recurring": {
        "total": 600000,
        "two_month_avg_monthly": 50000,
        "three_month_avg_monthly": 50000,
        "six_month_avg_monthly": 50000,
        "nine_month_avg_monthly": 50000,
        "twelve_month_avg_monthly": 50000
    },
    "non_recurring": {
        "total": 0,
        "two_month_avg_monthly": 0,
        "three_month_avg_monthly": 0,
        "six_month_avg_monthly": 0,
        "nine_month_avg_monthly": 0,
        "twelve_month_avg_monthly": 0
    },
    "summary_timespan_length": 361,
    "income_multiplier_threshold": 2.5,
    "income_multiplier": 2.6,
    "income_multiplier_result": "above",
    "income_criteria_results": null,
    "created_at": "04/11/2020"
}
</code></pre>

### Income Criteria

The schema for reports using income criteria (either individual or combined), differs slightly by having the `income_criteria_results` field comprise of the calculated criteria results instead of the top-level `income_multiplier_result` and `income_multiplier_threshold`, which are null when income criteria is used.

#### IncomeCriteriaResult Schema

| Field                  | Type             | Description                                                                                                                                                                                                                                                                                                                                 |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result`               | `string`         | `met`, `not_met`, or `unavailable` based on the calculation of the report data against the criteria used.                                                                                                                                                                                                                                   |
| `multiplier_result`    | `number \| null` | The value of the report's data as a multiplier of the rent amount for the criteria. `null` with the `account_name_mismatch_detection` criteria.                                                                                                                                                                                             |
| `multiplier_threshold` | `number \| null` | The threshold of value to rent ratio that was configured for organization. `null` with the `account_name_mismatch_detection` criteria.                                                                                                                                                                                                      |
| `criteria`             | `string`         | <p>Has the value of the criteria used in the calculation of the report data. See below section.<br><br>If a fallback criteria was configured and used when the prior criteria data in the report was unavailable, then it will be shown here.<br><br>If all criteria were unavailable for the report, the first criteria will be shown.</p> |

#### IncomeCriteria categories

| Criteria code                                            | Description                                                                                                                                                                                                              |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `two_month_avg_monthly_net_income_cents`                 | The applicant's average recurring income each month over the last two months. It only includes income that the applicant receives regularly.                                                                             |
| `three_month_avg_monthly_net_income_cents`               | The applicant's average recurring income each month over the last three months. Again, it only counts income that the applicant receives on a regular basis.                                                             |
| `two_month_avg_monthly_non_recurring_net_income_cents`   | The applicant's average non-recurring income each month for the past two months.                                                                                                                                         |
| `three_month_avg_monthly_non_recurring_net_income_cents` | The applicant's average non-recurring income each month over the last three months.                                                                                                                                      |
| `combined_two_month_avg_monthly_net_income_cents`        | The applicant's average income each month over the past two months, combining both recurring and non-recurring income.                                                                                                   |
| `combined_three_month_avg_monthly_net_income_cents`      | The applicant's average income each month over the past three months, combining both recurring and non-recurring income.                                                                                                 |
| `current_balance_sum_cents`                              | The sum of all of the applicant's current balance in their accounts                                                                                                                                                      |
| `available_balance_sum_cents`                            | The sum of all of the applicant's available balance in their accounts                                                                                                                                                    |
| `average_balance_sum_cents`                              | The sum of all of the applicant's average balance in their accounts                                                                                                                                                      |
| `account_name_mismatch_detection`                        | If the name(s) on the applicant's account(s) match the name they provided to us. If any of them don't match, the rule fails. If any names are missing or aren't returned by the bank, we don't count that as a mismatch. |

#### Sample Income Criteria results section

```
   "income_criteria_results": [
    {
      "result": "met",
      "multiplier_result": 3.3,
      "multiplier_threshold": 2.5,
      "criteria": "three_month_avg_monthly_net_income_cents"
    },
    {
      "result": "met",
      "multiplier_result": 3.8,
      "multiplier_threshold": 2.5,
      "criteria": "combined_three_month_avg_monthly_net_income_cents"
    },
    {
      "result": "not_met",
      "multiplier_result": 8.4,
      "multiplier_threshold": 10,
      "criteria": "available_balance_sum_cents"
    },
    {
      "result": "met",
      "multiplier_result": null,
      "multiplier_threshold": null,
      "criteria": "account_name_mismatch_detection"
    }
  ]
}
```


# Using Demo Bank Data

In the staging environment, you can create test income verification requests without charge. Here's how to use dummy bank data to test your workflow.

In the staging environment, you can create test income verification requests without charge. You can use our test bank credentials to get mock income data to populate your reports.

After you create a screening request, you will receive an invitation to the email(s) on the screening request. In the staging environment, you will send real emails.

When you begin to complete the income verification request, you’ll be prompted to authorize your bank account.

In order to use our test bank, search for the bank **Payscore** **Test Bank** and select that bank.

![](/files/YMqaZz0LlevVF6FgV7B9)

Enter the following credentials:\
\
**Username:** test\_user\
**Password:** password

![](/files/Q8wJgnpr2t0aEsLn30GV)

And you'll be connected to our test bank account.


# Introduction

Payscore's API allows you to send automated income, identity, or asset verification requests to a user.

## Getting Started

Every network request should be sent with the following headers:

| **Header**     | **Value**          |
| -------------- | ------------------ |
| `Accept`       | `application/json` |
| `Content-Type` | `application/json` |

### Environments

Payscore provides two environments: staging and production. The staging environment uses the following url:

```ruby
https://api.staging.payscore.com
```

Use the staging environment for development, as no charges will occur. For access to the staging environment, reach out to <support@payscore.com> and you will be provided a login.

The production environment is where all live production traffic should take place. Once you’re ready to gain production access, reach out to our team and we’ll provide you with a production login. Our production environment uses the following url:

```ruby
https://api.payscore.com
```


# Sending Invites

## Step 1: Create an authentication token

To get started with sending invites to your applicants, you first need to create an [authentication token](/api-reference/authentication) to make API requests.

## Step 2: Create an applicant group

Once you have a token, you can then start sending invites to your applicants by [creating an applicant group](/api-reference/applicant-groups) with the applicant information and their corresponding verifications that they are required to complete. This will automatically send invites to each applicant via email and text message, depending on whether the phone number was passed to Payscore.

{% 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** examples [here](/api-reference/applicant-groups).
{% endhint %}

Reminders are automatically sent to each applicant after 12 or 24 hours, with a maximum of 3 reminders. These settings can be configured in your portal.

## Step 3: Listen for webhooks

After the invite is sent, you can listen to our webhooks to get status updates on the verification and whether the report is ready or not.

## Step 4: Fetch the report

Once the applicant's verification is completed, you can fetch the report in either PDF or in JSON format.&#x20;


# Embedded Widget

Payscore’s embedded widget allows you to integrate our applicant workflow directly into your software without having the applicant leave your flow. This allows your applicant to stay in your world, while also allowing you to obtain the applicant’s verified income directly from their bank accounts.

The embedded experience has the ability to save the state for the applicant. That means that if an applicant closes the widget after connecting a bank account for whatever reason, the bank account will remain and the applicant can pick up where they left off.

While the applicant is in the embedded experience, Payscore also fully handles all support inquiries from the applicant through our live chat, which will be visible throughout the embedded experience.<br>

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXddXYpXKfOlwdaSzmoeqHBHv9UwcCBCZei0SJ312GBRhJqASASLSokhDVjlzLjJatloAGW_DjGpkv2Bqm79CFf9lRmjgcIfdXpvL3-Y5aRXbIi7Sjj1jiHqmmCWjUGQSfhQR345r4R7fmFSOobjjiPrUJs?key=6AQPPS-aW03uM1enmGnIJQ" alt=""><figcaption></figcaption></figure>


# Getting Started

## Installing the web SDK

Run one of the following commands at the root of your javascript project to install the SDK.

Using npm:

```bash
npm install --save @payscore/web-widget-sdk
```

Using yarn:

```bash
yarn add @payscore/web-widget-sdk
```

Please make sure your package version is at least 1.2.0

## Selecting an Appropriate Environment

Payscore provides two environments for usage with the web-widget-sdk.

`staging` is used to develop and test your integration.

`production` is used for your application’s live environment.

Developers should be aware that API calls to create an applicant group and widget token will require you to use the same environment you are passing into the widget configuration.

## Obtaining an Access Token

To interact with the Payscore API, you must first generate an access token and attach the token to the Authentication header to authenticate requests. To accomplish this, follow the instructions found in the [Authentication Documentation](/api-reference/authentication).

## Creating a Applicant Group for the Applicant

Before you load the embedded widget, an applicant group needs to be created for the applicant. For instructions on creating an Applicant Group, please see our [Applicant Group Documentation](https://payscore.gitbook.io/payscore-unpublished/api-reference/applicant-groups). Make sure you set the `is_invitation_disabled` parameter to `true` to avoid sending an email or a text message invite to the applicant.

Once an applicant group is created, store the applicant IDs for each applicant within the group. That applicant id is how Payscore knows which applicant’s verifications to show in the embedded widget.

## Generate an Authenticated Widget Token for the Current Applicant

To generate a widget token, you make a `GET` request to the `/api/v1/applicants/{applicant_id}/widget_token` endpoint from your back-end with the following headers, and will receive the following response. We recommend adding a proxy endpoint in your backend that your front-end calls to obtain the widget token.

```typescript
// Path
https://app.staging.payscore.com/api/v1/applicants/{applicant_id}/widget_token

// Headers
Method: 'GET'
Accept: 'application/json'
Content-Type: 'application/json'
Authorization: 'Bearer {accessToken}'


// Response
{
    'widget_token': '1234'
}
```

## Incorporating the SDK

To use the widget, see the code example below. We recommend producing a new widget token every time you open the embedded widget.

{% tabs fullWidth="true" %}
{% tab title="Typescript" %}
{% code fullWidth="true" %}

```typescript
import {
    IncomeVerificationWidget,
    PayscoreEventType,
    PayscoreEvent
} from '@payscore/web-widget-sdk'

const onEvent = (event: PayscoreEvent, widget: IncomeVerificationWidget) => {
    const { type, timestamp } = event;

    switch(type) {
        case PayscoreEventType.IncomeVerificationLoaded:
            // Your code here
            break;
        case PayscoreEventType.IncomeVerificationStarted:
            // Your code here
            break;
        case PayscoreEventType.IncomeVerificationCompleted:
            widget.unmount();
            // Your code here
            break;
    }
};

const { widgetToken } = // Your code here

const incomeVerificationWidgetOptions = {
    widgetToken,
    applicantId,
    environment: 'staging' | 'production',
    options: {
        // Prevent user from closing the widget themselves
        hideCloseButton: true
    },
    onEvent
};

const incomeVerificationWidget = new IncomeVerificationWidget(payscoreWidgetOptions);

incomeVerificationWidget.load();
```

{% endcode %}
{% endtab %}

{% tab title="React" %}
{% code fullWidth="true" %}

```tsx
import {
    IncomeVerificationWidget,
    PayscoreEvent,
    PayscoreEventType
} from '@payscore/web-widget-sdk';
import { FunctionComponent, useCallback, useEffect, useRef } from 'react';

export interface IncomeVerificationWidgetProps {
    applicantId: string;
    environment: 'staging' | 'production';
    widgetToken: string;
}

export const IncomeVerificationWidgetComponent: FunctionComponent<IncomeVerificationWidgetProps> = ({
    applicantId,
    environment,
    widgetToken,
}) => {
    const widgetRef = useRef<IncomeVerificationWidget | null>(null);

    const onEvent = useCallback(
        (event: PayscoreEvent, widget: IncomeVerificationWidget) => {
            const { type, timestamp } = event;

            switch (type) {
                case PayscoreEventType.IncomeVerificationLoaded:
                    // Your code here
                    break;
                case PayscoreEventType.IncomeVerificationStarted:
                    // Your code here
                    break;
                case PayscoreEventType.IncomeVerificationCompleted:
                    widget.unmount();
                    // Your code here
                    break;
            }
        },
        []
    );

    useEffect(() => {
        if (!widgetToken || !applicantId) {
            return;
        }

        const incomeVerificationWidgetOptions = {
            environment,
            onEvent,
            screeningId: applicantId,
            widgetToken,
        };

        const incomeVerificationWidget = new IncomeVerificationWidget(incomeVerificationWidgetOptions);
        widgetRef.current = incomeVerificationWidget;

        incomeVerificationWidget.load();

        return () => {
            if (widgetRef.current) {
                widgetRef.current.unmount();
                widgetRef.current = null;
            }
        };
    }, [applicantId, environment, onEvent, widgetToken]);

    return null;
};

```

{% endcode %}
{% endtab %}
{% endtabs %}


# Events

All events will have the following format, that includes a type and timestamp on the object. Certain events have a payload property with more event properties. See [#specific-event-payloads](#specific-event-payloads "mention") for more details.

```json
{
   type: 'payscore/incomeVerification/loaded',
   timestamp : "2011-12-19T15:28:46.493Z",
   payscore: true,
   methods: IncomeVerificationMethod[]
   payload?: Object
}
```

<table><thead><tr><th width="513.6015625">Event Type</th><th width="442.14453125">Description</th></tr></thead><tbody><tr><td><code>payscore/incomeVerification/loaded</code></td><td>Triggers when the widget loads.<br>Can be used to provide your own “widget loading” experience prior to widget mount.</td></tr><tr><td><code>payscore/incomeVerification/widgetClosed</code></td><td>Triggers when the embedded widget is manually closed by the applicant.</td></tr><tr><td><code>payscore/incomeVerification/started</code></td><td>Triggers when the applicant interacts with the workflow for the first time.</td></tr><tr><td><code>payscore/incomeVerification/institutionSelected</code></td><td>Triggers when an applicant selects a bank, payroll provider, or employer.</td></tr><tr><td><code>payscore/incomeVerification/institutionConnected</code></td><td>Triggers when an applicant successfully connects to their bank, payroll provider, or employer.</td></tr><tr><td><code>payscore/incomeVerification/loginAttempt</code></td><td>Triggers when an applicant attempts to login via bank or payroll provider</td></tr><tr><td><code>payscore/incomeVerification/loginAttemptFailed</code></td><td>Triggers when an attempted login fails. Most commonly seen with incorrect credentials, or an MFA challenge.<br><br>Bank login attempt failures include:<br>1. Incorrect credentials<br>2. Incorrect security answer<br>3. MFA challenge<br>4. Security questions expired<br>5. Account locked<br>6. Additional authorization required<br>7. User action required</td></tr><tr><td><code>payscore/incomeVerification/providerError</code></td><td>Triggers when an attempted login fails, or a connection to the provider cannot be made, for reasons outside of general login failure.  </td></tr><tr><td><code>payscore/incomeVerification/documentUploaded</code></td><td>Triggers when an applicant uploads a document.</td></tr><tr><td><code>payscore/incomeVerification/completed</code></td><td>Triggers when the applicant completes the workflow, fills out the feedback (or skips it), and submits the report. The widget should be closed after this event.</td></tr></tbody></table>

## Specific Event Payloads

Certain events contain payloads of data pertaining to the event that occurred. When using typescript, you can use the generic `PayscoreBaseEvent` type to narrow the payload value for your object.

**Payload resolution:**

<table data-header-hidden><thead><tr><th>Event Type</th><th>Payload</th></tr></thead><tbody><tr><td><code>payscore/incomeVerification/institutionConnected</code></td><td><pre class="language-ts"><code class="lang-ts">{ 
  institution: string;
  method: IncomeVerificationMethod
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/institutionSelected</code></td><td><pre><code>{ 
  institution: string;
  method: IncomeVerificationMethod
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/loginAttempt</code></td><td><pre><code>{
  institution: string;
  method: IncomeVerificationMethod;
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/loginAttemptFailed</code></td><td><pre><code>{
  institution: string;
  method: IncomeVerificationMethod;
}
</code></pre></td></tr><tr><td><code>payscore/incomeVerification/providerError</code></td><td><pre><code>{
  institution: string;
  method: IncomeVerificationMethod;
  errorMessage: string;
}
</code></pre></td></tr></tbody></table>

**Example:**

```ts
const onEvent = (event: PayscoreBaseEvent, widget: IncomeVerificationWidget) => {
    const { type, timestamp } = event;

    switch (type) {
        case PayscoreWidgetEventType.InstitutionConnected: {
            // Cast to narrow payload
            const { payload } = event as PayscoreBaseEvent<PayscoreWidgetEventType.InstitutionConnected>;
            console.log(payload.institution);
            break;
        }
    }
};
```

Pass the event type as the generic argument and TypeScript will enforce the correct `payload` shape — or `undefined` for event types that carry no payload.


# Webhooks

You can receive notifications from Payscore via webhooks when the following occurs:

* When an applicant has begun a verification request
* When an applicant successfully completes a verification request
* When a report is generated and ready to be viewed

The webhook will be sent as a `POST` request to the `webhook_url` attribute of the applicant group you created.

## `VERIFICATION_STARTED`

Payscore fires the `VERIFICATION_STARTED` webhook when an applicant begins the income verification request. This webhook does not fire more than once.

Example:

```json
{
    "code": "VERIFICATION_STARTED",
    "verification_id": "905963d4-0649-4046-8f39-7997a9e45ed4"
}
```

## `VERIFICATION_COMPLETED`

Once the applicant finishes a verification, the `VERIFICATION_COMPLETED` webhook will fire.

Example:

```json
{
    "code": "VERIFICATION_COMPLETED",
    "verification_id": "905963d4-0649-4046-8f39-7997a9e45ed4",
    "reason_completed": "finished"
}
```

{% hint style="warning" %}
This webhook might fire several times due to an applicant re-opening their verification in order to add/remove an account or modify their explanation. Be sure to update your report whenever this webhook fires in order to show the most updated report.
{% endhint %}

## `REPORT_READY`

Once a report has been generated and ready to be viewed, the `REPORT_READY` webhook will fire. This is different from the `VERIFICATION_COMPLETED` webhook since some reports like the household income report require all applicants to complete the verification before a report is generated.

The `report_type` field will allow you to determine which type of report to expect when fetching the report's PDF or JSON data. Values can be `income`, `asset` , or `identity` .

For reports for individual applicants (such as identity verification reports), the `applicant_id` field will be present to allow you to correlate the report to the individual applicant. Household reports like `income` will be correlated to the entire applicant group.

The `report_id` will be used for you to fetch the report data.

Example:

```json
{
    "code": "REPORT_READY",
    "applicant_group_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
    "applicant_id": "4516efb4-82ed-43cd-a55a-ba93d4914562",
    "report_id": "2d376488-fc60-4193-bac2-1023764b7842",
    "report_type": "income"
}
```


# Validating Webhooks

When a webhook is sent, Payscore uses the webhook body and your secret key to create a hash signature, which is sent in the header `Verification-Signature`. The hash is created using HMAC-SHA256 and is hex encoded.&#x20;

In order for you to validate that the webhook is legitimate, hash the raw webhook body using your secret key as the key, and then compare your generated signature with the `Verification-Signature`  header value.

{% hint style="warning" %}
**Do Not Parse or Cast the Webhook Request Body**\
While generating the signature at your end, ensure that the webhook body passed as an argument is the raw webhook request body. Do not parse or cast the webhook request body.
{% endhint %}


# Using Demo Bank Data

In the staging environment, you can create test income verification requests without charge. You can use our test bank credentials to get mock income data to populate your reports.

After you create a screening request, you will receive an invitation to the email(s) on the screening request. In the staging environment, you will send real emails.

When you begin to complete the income verification request, you’ll be prompted to authorize your bank account.

In order to use our test bank, search for the bank **Payscore** **Test Bank** and select that bank.

![](/files/YMqaZz0LlevVF6FgV7B9)

Enter the following credentials:\
\
**Username:** test\_user\
**Password:** password

![](/files/Q8wJgnpr2t0aEsLn30GV)

And you'll be connected to our test bank account.


# Authentication

## Authenticate and obtain access token

> Authenticate using your client credentials to obtain an access token. The token expires after 30 minutes and must be included in the Authorization header for all subsequent API requests. The access token will be returned in the Authorization header.

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Authentication"}],"servers":[{"url":"https://api.payscore.com","description":"Production server"},{"url":"https://staging.api.payscore.com","description":"Staging server"}],"security":[],"paths":{"/api/v1/tenants/auth":{"post":{"summary":"Authenticate and obtain access token","description":"Authenticate using your client credentials to obtain an access token. The token expires after 30 minutes and must be included in the Authorization header for all subsequent API requests. The access token will be returned in the Authorization header.","operationId":"authenticateTenant","tags":["Authentication"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_id","secret_key"],"properties":{"client_id":{"type":"string","description":"Your client ID provided by Payscore"},"secret_key":{"type":"string","description":"Your secret key provided by Payscore"}}}}}},"responses":{"200":{"description":"Authentication successful","headers":{"Authorization":{"description":"Bearer token for API authentication","schema":{"type":"string"},"required":true}}},"401":{"description":"Authentication failed - invalid client credentials"}}}}}}
```


# Applicant Groups

## List all applicant groups

> Retrieves a paginated list of all applicant groups. Supports filtering by status, correlation ID, creation date range, and search query.

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Applicant Groups"}],"servers":[{"url":"https://api.payscore.com","description":"Production server"},{"url":"https://staging.api.payscore.com","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from the `/api/v1/tenants/auth` endpoint.\nToken expires after 30 minutes and must be refreshed.\n\nExample: `Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...`\n"}},"schemas":{"ApplicantGroup":{"type":"object","description":"An applicant group represents a verification request for multiple applicants","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"decision_maker_display_name":{"type":"string","description":"Display name for the decision maker"},"property":{"type":"object","description":"Property information where applicants will be residing","properties":{"id":{"type":"string","format":"uuid","description":"Property unique identifier"},"name":{"type":"string","description":"Property name"},"street_address":{"type":"string","description":"Property street address"},"city":{"type":"string","description":"Property city"},"state":{"type":"string","description":"Property state"},"zip_code":{"type":"string","description":"Property ZIP code"}}},"status":{"type":"string","description":"Current status of the applicant group","enum":["not_started","in_progress","completed"]},"created_at_timestamp":{"type":"number","format":"float","description":"Unix timestamp when the applicant group was created"},"monthly_rent_cents":{"type":"integer","description":"Monthly rent amount in cents"},"unit_number":{"type":"string","description":"Unit number or identifier"},"unit_id":{"type":"string","format":"uuid","description":"Unique identifier for the unit","nullable":true},"is_free":{"type":"boolean","description":"Whether this is a free verification"},"is_decision_maker_paying":{"type":"boolean","description":"Whether the decision maker is paying for the verification"},"correlation_id":{"type":"string","description":"External system correlation identifier","nullable":true},"verification_types":{"type":"array","description":"List of unique verification types across all applicants in this group","items":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"]}},"is_expired":{"type":"boolean","description":"Whether the applicant group has expired"},"applicants":{"type":"array","description":"List of applicants in this group","items":{"$ref":"#/components/schemas/Applicant"}}}},"Applicant":{"type":"object","description":"An individual applicant within an applicant group","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant"},"first_name":{"type":"string","description":"Applicant's first name"},"last_name":{"type":"string","description":"Applicant's last name"},"email":{"type":"string","format":"email","description":"Applicant's email address"},"phone_number":{"type":"string","description":"Applicant's phone number"},"created_at":{"type":"string","format":"date-time","description":"When the applicant was created"},"updated_at":{"type":"string","format":"date-time","description":"When the applicant was last updated"},"verifications":{"type":"array","description":"List of verifications assigned to this applicant. Note - This field is only included in detail view on create, not in list views (e.g., when fetching multiple applicant groups).","items":{"$ref":"#/components/schemas/Verification"}}}},"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}},"paths":{"/api/v1/applicant_groups":{"get":{"summary":"List all applicant groups","description":"Retrieves a paginated list of all applicant groups. Supports filtering by status, correlation ID, creation date range, and search query.","operationId":"listApplicantGroups","tags":["Applicant Groups"],"parameters":[{"name":"search","in":"query","description":"Search query to filter applicant groups","schema":{"type":"string"}},{"name":"statuses","in":"query","description":"Comma-separated list of statuses to filter by","schema":{"type":"string"}},{"name":"correlation_id","in":"query","description":"Filter by external correlation identifier","schema":{"type":"string"}},{"name":"created_after","in":"query","description":"Filter applicant groups created after this Unix timestamp","schema":{"type":"integer","format":"int"}},{"name":"created_before","in":"query","description":"Filter applicant groups created before this Unix timestamp","schema":{"type":"integer","format":"int"}},{"name":"page","in":"query","description":"Page number for pagination","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"List of applicant groups retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"applicant_groups":{"type":"array","items":{"$ref":"#/components/schemas/ApplicantGroup"}},"total_count":{"type":"integer","description":"Total number of applicant groups matching the query"}}}}}},"401":{"description":"Unauthorized - invalid or missing authentication token"}}}}}}
```

## Create a new applicant group

> Creates a new applicant group to send applicants their corresponding verifications. When an applicant group is created successfully, an email and/or text is sent to all applicants inviting them to complete their verifications unless the invitation is disabled.

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Applicant Groups"}],"servers":[{"url":"https://api.payscore.com","description":"Production server"},{"url":"https://staging.api.payscore.com","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from the `/api/v1/tenants/auth` endpoint.\nToken expires after 30 minutes and must be refreshed.\n\nExample: `Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...`\n"}},"schemas":{"ApplicantGroup":{"type":"object","description":"An applicant group represents a verification request for multiple applicants","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"decision_maker_display_name":{"type":"string","description":"Display name for the decision maker"},"property":{"type":"object","description":"Property information where applicants will be residing","properties":{"id":{"type":"string","format":"uuid","description":"Property unique identifier"},"name":{"type":"string","description":"Property name"},"street_address":{"type":"string","description":"Property street address"},"city":{"type":"string","description":"Property city"},"state":{"type":"string","description":"Property state"},"zip_code":{"type":"string","description":"Property ZIP code"}}},"status":{"type":"string","description":"Current status of the applicant group","enum":["not_started","in_progress","completed"]},"created_at_timestamp":{"type":"number","format":"float","description":"Unix timestamp when the applicant group was created"},"monthly_rent_cents":{"type":"integer","description":"Monthly rent amount in cents"},"unit_number":{"type":"string","description":"Unit number or identifier"},"unit_id":{"type":"string","format":"uuid","description":"Unique identifier for the unit","nullable":true},"is_free":{"type":"boolean","description":"Whether this is a free verification"},"is_decision_maker_paying":{"type":"boolean","description":"Whether the decision maker is paying for the verification"},"correlation_id":{"type":"string","description":"External system correlation identifier","nullable":true},"verification_types":{"type":"array","description":"List of unique verification types across all applicants in this group","items":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"]}},"is_expired":{"type":"boolean","description":"Whether the applicant group has expired"},"applicants":{"type":"array","description":"List of applicants in this group","items":{"$ref":"#/components/schemas/Applicant"}}}},"Applicant":{"type":"object","description":"An individual applicant within an applicant group","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant"},"first_name":{"type":"string","description":"Applicant's first name"},"last_name":{"type":"string","description":"Applicant's last name"},"email":{"type":"string","format":"email","description":"Applicant's email address"},"phone_number":{"type":"string","description":"Applicant's phone number"},"created_at":{"type":"string","format":"date-time","description":"When the applicant was created"},"updated_at":{"type":"string","format":"date-time","description":"When the applicant was last updated"},"verifications":{"type":"array","description":"List of verifications assigned to this applicant. Note - This field is only included in detail view on create, not in list views (e.g., when fetching multiple applicant groups).","items":{"$ref":"#/components/schemas/Verification"}}}},"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}},"paths":{"/api/v1/applicant_groups":{"post":{"summary":"Create a new applicant group","description":"Creates a new applicant group to send applicants their corresponding verifications. When an applicant group is created successfully, an email and/or text is sent to all applicants inviting them to complete their verifications unless the invitation is disabled.","operationId":"createApplicantGroup","tags":["Applicant Groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["applicants","property","decision_maker_display_name","monthly_rent"],"properties":{"applicants":{"type":"array","description":"The applicants attached to the verification request","minItems":1,"items":{"type":"object","required":["first_name","last_name","email","verifications"],"properties":{"first_name":{"type":"string","description":"Applicant's first name"},"last_name":{"type":"string","description":"Applicant's last name"},"email":{"type":"string","format":"email","description":"Applicant's email address. This is the email address where we will send the verification invite"},"phone_number":{"type":"string","description":"Applicant's phone number, including the international code (ex. +19842342345). \nIncluding this will send a text message invite as well as an email.\n"},"verifications":{"type":"array","description":"Types of verification to be sent to applicant","minItems":1,"items":{"type":"object","properties":{"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"allowed_income_sources":{"type":"array","description":"Restricts which income sources the applicant may use to complete a flexible_income_verification.\nOnly applicable when type is flexible_income_verification. If omitted, the tenant's default\nallowed income sources are used.\n","items":{"type":"string","enum":["bank","payroll","applicant_document","support_document"]}}}}}}}},"property":{"type":"object","description":"The property's address that will be displayed in the applicant workflow to let the applicant know they are in the right place.","required":["name","street_address","city","state","zip_code"],"properties":{"name":{"type":"string","description":"The property's name"},"street_address":{"type":"string","description":"The property's street address"},"city":{"type":"string","description":"The property's city"},"state":{"type":"string","description":"The property's state"},"zip_code":{"type":"string","description":"The property's ZIP code"},"unit":{"type":"string","description":"Unit number"}}},"decision_maker_display_name":{"type":"string","description":"Display name for the decision maker"},"monthly_rent":{"type":"number","format":"integer","description":"Monthly rent amount in dollars"},"webhook_url":{"type":"string","description":"The URL that will receive webhook notifications for the applicant group created.\n"},"is_invitation_disabled":{"type":"boolean","description":"If you decide to not want Payscore to invite the applicant via email and/or text, pass in true for this field.\nIf you are utilizing our embedded widget, you will want to pass in true to this field.\n"},"correlation_id":{"type":"string","description":"External system correlation identifier"},"config":{"type":"object","description":"Optional configuration overrides for this applicant group","properties":{"block_business_accounts":{"type":"boolean","description":"When true, applicants will be blocked from connecting business bank accounts\nor uploading business statements during income verification. Defaults to false if not included.\n"}}}}}}}},"responses":{"200":{"description":"Applicant group created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicantGroup"}}}},"400":{"description":"Bad request - validation errors","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}}}}}}
```


# Reports

## Get reports for an applicant group

> Retrieves all household and individual reports associated with a specific applicant group. Returns both household-level reports (aggregated across all applicants) and individual applicant reports.

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Reports"}],"servers":[{"url":"https://api.payscore.com","description":"Production server"},{"url":"https://staging.api.payscore.com","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from the `/api/v1/tenants/auth` endpoint.\nToken expires after 30 minutes and must be refreshed.\n\nExample: `Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...`\n"}},"schemas":{"Report":{"type":"object","description":"A report generated from a completed verification","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the report"},"report_name":{"type":"string","enum":["Income","Identity","Asset"],"description":"Name of the report"},"is_expired":{"type":"boolean","description":"Whether the report data has expired and is no longer available"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group this report belongs to (only present for household reports, not individual reports)"},"applicant_id":{"type":"string","format":"uuid","description":"Unique identifier for the individual applicant (only present for individual reports, not household reports)","nullable":true},"path":{"type":"string","description":"URL path to view the pdf"}}}}},"paths":{"/api/v1/applicant_groups/{id}/reports":{"get":{"summary":"Get reports for an applicant group","description":"Retrieves all household and individual reports associated with a specific applicant group. Returns both household-level reports (aggregated across all applicants) and individual applicant reports.","operationId":"getApplicantGroupReports","tags":["Reports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the applicant group","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Reports retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"household_reports":{"type":"array","description":"Household-level reports aggregating data across all applicants such as for income","items":{"$ref":"#/components/schemas/Report"}},"individual_reports":{"type":"array","description":"Individual reports for each applicant such as for identity","items":{"$ref":"#/components/schemas/Report"}}}}}}},"401":{"description":"Unauthorized - invalid or missing authentication token"},"404":{"description":"Applicant group not found"}}}}}}
```

## Get report data

> Retrieves the data for a specific report. The response structure varies based on the report type (income, identity, or asset verification).

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"tags":[{"name":"Reports"}],"servers":[{"url":"https://api.payscore.com","description":"Production server"},{"url":"https://staging.api.payscore.com","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from the `/api/v1/tenants/auth` endpoint.\nToken expires after 30 minutes and must be refreshed.\n\nExample: `Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...`\n"}},"schemas":{"ReportDataResponse":{"type":"object","description":"Wrapper response containing report data that varies by report type, including PDF download URL","required":["report_id","report_type","applicant_group_id","pdf_url","data"],"properties":{"report_id":{"type":"string","format":"uuid","description":"Unique identifier for the report"},"report_type":{"type":"string","enum":["income","identity"],"description":"Type of report data contained in this response"},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group this report belongs to"},"applicant_id":{"type":"string","format":"uuid","description":"Unique identifier for the individual applicant (only present for individual reports, not household reports)"},"pdf_url":{"type":"string","format":"uri","description":"Secure URL to download the PDF report (expires in 2 hours)"},"data":{"oneOf":[{"$ref":"#/components/schemas/IncomeReportData"},{"$ref":"#/components/schemas/IdentityReportData"}],"discriminator":{"propertyName":"report_type","mapping":{"income":"#/components/schemas/IncomeReportData","identity":"#/components/schemas/IdentityReportData"}}}}},"IncomeReportData":{"description":"Income report data — either a household (combined) report or an individual applicant report","oneOf":[{"$ref":"#/components/schemas/HouseholdIncomeReport"},{"$ref":"#/components/schemas/IndividualIncomeReport"}]},"HouseholdIncomeReport":{"type":"object","description":"Combined income report aggregating data across all applicants in the group. Contains a reports array with each applicant's individual sub-report.","properties":{"reports":{"type":"array","description":"Individual income sub-reports for each applicant in the group","items":{"$ref":"#/components/schemas/ApplicantIncomeSubReport"}},"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Minimum data timespan across all applicants, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded across all applicants for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"ApplicantIncomeSubReport":{"type":"object","description":"An individual applicant's income data nested within a HouseholdIncomeReport. Contains richer per-applicant detail than the top-level individual report.","properties":{"verification_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant's income verification"},"identity":{"type":"object","description":"Identity information for this applicant","properties":{"full_name":{"type":"string"},"email":{"type":"string","format":"email"}}},"reason_completed":{"type":"string","nullable":true,"description":"Reason the verification was completed"},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RecurringIncomeData"}]},"non_recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NonRecurringIncomeData"}]},"summary_timespan_length":{"type":"integer","nullable":true,"description":"Data timespan for this applicant, in days"},"bank_connections":{"type":"array","nullable":true,"description":"Income summaries for each linked bank connection (bank income source only)","items":{"$ref":"#/components/schemas/BankConnectionIncomeSummary"}},"payroll_connections":{"type":"array","nullable":true,"description":"Income summaries for each payroll connection (payroll income source only)","items":{"$ref":"#/components/schemas/PayrollConnectionIncomeSummary"}},"income_explanation":{"type":"string","nullable":true,"description":"Human-readable explanation of the income determination (bank income source only)"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by this applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}},"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"BankConnectionIncomeSummary":{"type":"object","description":"Income summary for a single linked bank connection","properties":{"institution_name":{"type":"string","description":"Name of the financial institution"},"accounts":{"type":"array","description":"Bank accounts on this connection used for income analysis","items":{"type":"object","description":"Account properties including name, holder names, type, and balances"}},"income":{"type":"object","description":"Aggregated income analysis for this bank connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents"},"income_streams":{"type":"array","description":"Recurring income streams identified for this bank connection","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"non_recurring":{"type":"object","description":"Non-recurring income for this bank connection","properties":{"total":{"type":"integer","description":"Total non-recurring income in cents"},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"start_date":{"type":"string","format":"date","description":"Earliest transaction date across all income streams"},"end_date":{"type":"string","format":"date","description":"Latest transaction date across all income streams"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by income transactions"}}}}},"PayrollConnectionIncomeSummary":{"type":"object","description":"Income summary for a single payroll connection","properties":{"employee_name":{"type":"string","nullable":true,"description":"Employee name as reported by the payroll provider"},"company_name":{"type":"string","nullable":true,"description":"Employer company name"},"institution_name":{"type":"string","nullable":true,"description":"Name of the payroll provider"},"company_address":{"type":"string","nullable":true,"description":"Employer address"},"title":{"type":"string","nullable":true,"description":"Job title"},"start_date":{"type":"string","nullable":true,"description":"Employment start date"},"end_date":{"type":"string","nullable":true,"description":"Employment end date (null if currently employed)"},"pay_frequency":{"type":"string","nullable":true,"description":"Pay frequency"},"pay_rate":{"type":"string","nullable":true,"description":"Pay rate description"},"pay_amount":{"type":"integer","nullable":true,"description":"Pay amount in cents"},"income":{"type":"object","nullable":true,"description":"Aggregated income analysis for this payroll connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true},"three_month_avg_monthly":{"type":"integer","nullable":true},"six_month_avg_monthly":{"type":"integer","nullable":true},"nine_month_avg_monthly":{"type":"integer","nullable":true},"twelve_month_avg_monthly":{"type":"integer","nullable":true},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"start_date":{"type":"string","format":"date","description":"Earliest paystub date"},"end_date":{"type":"string","format":"date","description":"Latest paystub date"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by paystubs"}}},"is_name_mismatched":{"type":"boolean","description":"Whether the employee name on paystubs does not match the applicant name"}}},"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"Fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}},"IncomeCriteriaResult":{"type":"object","description":"Result of evaluating a single income criteria rule","properties":{"result":{"type":"string","description":"Whether the applicant passed or failed this criteria"},"multiplier_result":{"type":"string","nullable":true,"description":"Income-to-rent multiplier result for this criteria"},"multiplier_threshold":{"type":"number","nullable":true,"description":"The multiplier threshold used in this criteria evaluation"},"criteria_used":{"type":"string","nullable":true,"description":"The specific income figure used for evaluation (e.g., which monthly average)"},"criteria_from_rule":{"type":"string","nullable":true,"description":"The rule that determined which income criteria to use"}}},"IndividualIncomeReport":{"type":"object","description":"Income report for a single applicant fetched directly. Has the same exposed fields as HouseholdIncomeReport but includes income_sources and no reports array.","properties":{"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Data timespan, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by the applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"IdentityReportData":{"type":"object","description":"Identity verification report data from a completed identity verification","properties":{"outcome":{"type":"string","enum":["passed","failed"],"description":"Overall outcome of the identity verification"},"verification_types":{"type":"array","description":"Types of verification performed (e.g., government_id, selfie, tin, ecbsv)","items":{"type":"string","enum":["government_id","selfie","tin","ecbsv"]}},"checks":{"type":"array","description":"Individual verification checks performed during identity verification","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification check"},"identity_verification_id":{"type":"string","format":"uuid","description":"ID of the parent identity verification"},"name":{"type":"string","description":"Specific check name (e.g., id_entity_detection, selfie_liveness_detection)"},"verification_type":{"type":"string","enum":["government_id","selfie","tin","ecbsv"],"description":"Type of verification performed"},"status":{"type":"string","enum":["passed","failed","not_applicable"],"description":"Status of the verification check"},"reasons":{"type":"array","description":"Array of reason codes for check failure","items":{"type":"string"}},"metadata":{"type":"object","description":"Additional metadata about the check","nullable":true}}}}}}}},"paths":{"/api/v1/reports/{id}":{"get":{"summary":"Get report data","description":"Retrieves the data for a specific report. The response structure varies based on the report type (income, identity, or asset verification).","operationId":"getReportData","tags":["Reports"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the report","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Report data retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDataResponse"}}}},"404":{"description":"Report not found"},"410":{"description":"Report data has expired and is no longer available"}}}}}}
```


# Models

## The ApplicantGroup object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"ApplicantGroup":{"type":"object","description":"An applicant group represents a verification request for multiple applicants","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"decision_maker_display_name":{"type":"string","description":"Display name for the decision maker"},"property":{"type":"object","description":"Property information where applicants will be residing","properties":{"id":{"type":"string","format":"uuid","description":"Property unique identifier"},"name":{"type":"string","description":"Property name"},"street_address":{"type":"string","description":"Property street address"},"city":{"type":"string","description":"Property city"},"state":{"type":"string","description":"Property state"},"zip_code":{"type":"string","description":"Property ZIP code"}}},"status":{"type":"string","description":"Current status of the applicant group","enum":["not_started","in_progress","completed"]},"created_at_timestamp":{"type":"number","format":"float","description":"Unix timestamp when the applicant group was created"},"monthly_rent_cents":{"type":"integer","description":"Monthly rent amount in cents"},"unit_number":{"type":"string","description":"Unit number or identifier"},"unit_id":{"type":"string","format":"uuid","description":"Unique identifier for the unit","nullable":true},"is_free":{"type":"boolean","description":"Whether this is a free verification"},"is_decision_maker_paying":{"type":"boolean","description":"Whether the decision maker is paying for the verification"},"correlation_id":{"type":"string","description":"External system correlation identifier","nullable":true},"verification_types":{"type":"array","description":"List of unique verification types across all applicants in this group","items":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"]}},"is_expired":{"type":"boolean","description":"Whether the applicant group has expired"},"applicants":{"type":"array","description":"List of applicants in this group","items":{"$ref":"#/components/schemas/Applicant"}}}},"Applicant":{"type":"object","description":"An individual applicant within an applicant group","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant"},"first_name":{"type":"string","description":"Applicant's first name"},"last_name":{"type":"string","description":"Applicant's last name"},"email":{"type":"string","format":"email","description":"Applicant's email address"},"phone_number":{"type":"string","description":"Applicant's phone number"},"created_at":{"type":"string","format":"date-time","description":"When the applicant was created"},"updated_at":{"type":"string","format":"date-time","description":"When the applicant was last updated"},"verifications":{"type":"array","description":"List of verifications assigned to this applicant. Note - This field is only included in detail view on create, not in list views (e.g., when fetching multiple applicant groups).","items":{"$ref":"#/components/schemas/Verification"}}}},"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}}}
```

## The Applicant object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"Applicant":{"type":"object","description":"An individual applicant within an applicant group","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant"},"first_name":{"type":"string","description":"Applicant's first name"},"last_name":{"type":"string","description":"Applicant's last name"},"email":{"type":"string","format":"email","description":"Applicant's email address"},"phone_number":{"type":"string","description":"Applicant's phone number"},"created_at":{"type":"string","format":"date-time","description":"When the applicant was created"},"updated_at":{"type":"string","format":"date-time","description":"When the applicant was last updated"},"verifications":{"type":"array","description":"List of verifications assigned to this applicant. Note - This field is only included in detail view on create, not in list views (e.g., when fetching multiple applicant groups).","items":{"$ref":"#/components/schemas/Verification"}}}},"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}}}
```

## The Verification object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"Verification":{"type":"object","description":"A verification assigned to an applicant","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification"},"type":{"type":"string","enum":["asset_verification","identity_verification","payroll_income_verification","bank_income_verification","flexible_income_verification","document_income_verification"],"description":"Type of verification"},"status":{"type":"string","description":"Current status of the verification","enum":["not_started","in_progress","completed"]}}}}}}
```

## The Report object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"Report":{"type":"object","description":"A report generated from a completed verification","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the report"},"report_name":{"type":"string","enum":["Income","Identity","Asset"],"description":"Name of the report"},"is_expired":{"type":"boolean","description":"Whether the report data has expired and is no longer available"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group this report belongs to (only present for household reports, not individual reports)"},"applicant_id":{"type":"string","format":"uuid","description":"Unique identifier for the individual applicant (only present for individual reports, not household reports)","nullable":true},"path":{"type":"string","description":"URL path to view the pdf"}}}}}}
```

## The ReportDataResponse object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"ReportDataResponse":{"type":"object","description":"Wrapper response containing report data that varies by report type, including PDF download URL","required":["report_id","report_type","applicant_group_id","pdf_url","data"],"properties":{"report_id":{"type":"string","format":"uuid","description":"Unique identifier for the report"},"report_type":{"type":"string","enum":["income","identity"],"description":"Type of report data contained in this response"},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group this report belongs to"},"applicant_id":{"type":"string","format":"uuid","description":"Unique identifier for the individual applicant (only present for individual reports, not household reports)"},"pdf_url":{"type":"string","format":"uri","description":"Secure URL to download the PDF report (expires in 2 hours)"},"data":{"oneOf":[{"$ref":"#/components/schemas/IncomeReportData"},{"$ref":"#/components/schemas/IdentityReportData"}],"discriminator":{"propertyName":"report_type","mapping":{"income":"#/components/schemas/IncomeReportData","identity":"#/components/schemas/IdentityReportData"}}}}},"IncomeReportData":{"description":"Income report data — either a household (combined) report or an individual applicant report","oneOf":[{"$ref":"#/components/schemas/HouseholdIncomeReport"},{"$ref":"#/components/schemas/IndividualIncomeReport"}]},"HouseholdIncomeReport":{"type":"object","description":"Combined income report aggregating data across all applicants in the group. Contains a reports array with each applicant's individual sub-report.","properties":{"reports":{"type":"array","description":"Individual income sub-reports for each applicant in the group","items":{"$ref":"#/components/schemas/ApplicantIncomeSubReport"}},"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Minimum data timespan across all applicants, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded across all applicants for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"ApplicantIncomeSubReport":{"type":"object","description":"An individual applicant's income data nested within a HouseholdIncomeReport. Contains richer per-applicant detail than the top-level individual report.","properties":{"verification_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant's income verification"},"identity":{"type":"object","description":"Identity information for this applicant","properties":{"full_name":{"type":"string"},"email":{"type":"string","format":"email"}}},"reason_completed":{"type":"string","nullable":true,"description":"Reason the verification was completed"},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RecurringIncomeData"}]},"non_recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NonRecurringIncomeData"}]},"summary_timespan_length":{"type":"integer","nullable":true,"description":"Data timespan for this applicant, in days"},"bank_connections":{"type":"array","nullable":true,"description":"Income summaries for each linked bank connection (bank income source only)","items":{"$ref":"#/components/schemas/BankConnectionIncomeSummary"}},"payroll_connections":{"type":"array","nullable":true,"description":"Income summaries for each payroll connection (payroll income source only)","items":{"$ref":"#/components/schemas/PayrollConnectionIncomeSummary"}},"income_explanation":{"type":"string","nullable":true,"description":"Human-readable explanation of the income determination (bank income source only)"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by this applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}},"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"BankConnectionIncomeSummary":{"type":"object","description":"Income summary for a single linked bank connection","properties":{"institution_name":{"type":"string","description":"Name of the financial institution"},"accounts":{"type":"array","description":"Bank accounts on this connection used for income analysis","items":{"type":"object","description":"Account properties including name, holder names, type, and balances"}},"income":{"type":"object","description":"Aggregated income analysis for this bank connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents"},"income_streams":{"type":"array","description":"Recurring income streams identified for this bank connection","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"non_recurring":{"type":"object","description":"Non-recurring income for this bank connection","properties":{"total":{"type":"integer","description":"Total non-recurring income in cents"},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"start_date":{"type":"string","format":"date","description":"Earliest transaction date across all income streams"},"end_date":{"type":"string","format":"date","description":"Latest transaction date across all income streams"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by income transactions"}}}}},"PayrollConnectionIncomeSummary":{"type":"object","description":"Income summary for a single payroll connection","properties":{"employee_name":{"type":"string","nullable":true,"description":"Employee name as reported by the payroll provider"},"company_name":{"type":"string","nullable":true,"description":"Employer company name"},"institution_name":{"type":"string","nullable":true,"description":"Name of the payroll provider"},"company_address":{"type":"string","nullable":true,"description":"Employer address"},"title":{"type":"string","nullable":true,"description":"Job title"},"start_date":{"type":"string","nullable":true,"description":"Employment start date"},"end_date":{"type":"string","nullable":true,"description":"Employment end date (null if currently employed)"},"pay_frequency":{"type":"string","nullable":true,"description":"Pay frequency"},"pay_rate":{"type":"string","nullable":true,"description":"Pay rate description"},"pay_amount":{"type":"integer","nullable":true,"description":"Pay amount in cents"},"income":{"type":"object","nullable":true,"description":"Aggregated income analysis for this payroll connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true},"three_month_avg_monthly":{"type":"integer","nullable":true},"six_month_avg_monthly":{"type":"integer","nullable":true},"nine_month_avg_monthly":{"type":"integer","nullable":true},"twelve_month_avg_monthly":{"type":"integer","nullable":true},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"start_date":{"type":"string","format":"date","description":"Earliest paystub date"},"end_date":{"type":"string","format":"date","description":"Latest paystub date"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by paystubs"}}},"is_name_mismatched":{"type":"boolean","description":"Whether the employee name on paystubs does not match the applicant name"}}},"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"Fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}},"IncomeCriteriaResult":{"type":"object","description":"Result of evaluating a single income criteria rule","properties":{"result":{"type":"string","description":"Whether the applicant passed or failed this criteria"},"multiplier_result":{"type":"string","nullable":true,"description":"Income-to-rent multiplier result for this criteria"},"multiplier_threshold":{"type":"number","nullable":true,"description":"The multiplier threshold used in this criteria evaluation"},"criteria_used":{"type":"string","nullable":true,"description":"The specific income figure used for evaluation (e.g., which monthly average)"},"criteria_from_rule":{"type":"string","nullable":true,"description":"The rule that determined which income criteria to use"}}},"IndividualIncomeReport":{"type":"object","description":"Income report for a single applicant fetched directly. Has the same exposed fields as HouseholdIncomeReport but includes income_sources and no reports array.","properties":{"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Data timespan, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by the applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"IdentityReportData":{"type":"object","description":"Identity verification report data from a completed identity verification","properties":{"outcome":{"type":"string","enum":["passed","failed"],"description":"Overall outcome of the identity verification"},"verification_types":{"type":"array","description":"Types of verification performed (e.g., government_id, selfie, tin, ecbsv)","items":{"type":"string","enum":["government_id","selfie","tin","ecbsv"]}},"checks":{"type":"array","description":"Individual verification checks performed during identity verification","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification check"},"identity_verification_id":{"type":"string","format":"uuid","description":"ID of the parent identity verification"},"name":{"type":"string","description":"Specific check name (e.g., id_entity_detection, selfie_liveness_detection)"},"verification_type":{"type":"string","enum":["government_id","selfie","tin","ecbsv"],"description":"Type of verification performed"},"status":{"type":"string","enum":["passed","failed","not_applicable"],"description":"Status of the verification check"},"reasons":{"type":"array","description":"Array of reason codes for check failure","items":{"type":"string"}},"metadata":{"type":"object","description":"Additional metadata about the check","nullable":true}}}}}}}}}
```

## The IncomeReportData object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"IncomeReportData":{"description":"Income report data — either a household (combined) report or an individual applicant report","oneOf":[{"$ref":"#/components/schemas/HouseholdIncomeReport"},{"$ref":"#/components/schemas/IndividualIncomeReport"}]},"HouseholdIncomeReport":{"type":"object","description":"Combined income report aggregating data across all applicants in the group. Contains a reports array with each applicant's individual sub-report.","properties":{"reports":{"type":"array","description":"Individual income sub-reports for each applicant in the group","items":{"$ref":"#/components/schemas/ApplicantIncomeSubReport"}},"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Minimum data timespan across all applicants, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded across all applicants for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"ApplicantIncomeSubReport":{"type":"object","description":"An individual applicant's income data nested within a HouseholdIncomeReport. Contains richer per-applicant detail than the top-level individual report.","properties":{"verification_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant's income verification"},"identity":{"type":"object","description":"Identity information for this applicant","properties":{"full_name":{"type":"string"},"email":{"type":"string","format":"email"}}},"reason_completed":{"type":"string","nullable":true,"description":"Reason the verification was completed"},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RecurringIncomeData"}]},"non_recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NonRecurringIncomeData"}]},"summary_timespan_length":{"type":"integer","nullable":true,"description":"Data timespan for this applicant, in days"},"bank_connections":{"type":"array","nullable":true,"description":"Income summaries for each linked bank connection (bank income source only)","items":{"$ref":"#/components/schemas/BankConnectionIncomeSummary"}},"payroll_connections":{"type":"array","nullable":true,"description":"Income summaries for each payroll connection (payroll income source only)","items":{"$ref":"#/components/schemas/PayrollConnectionIncomeSummary"}},"income_explanation":{"type":"string","nullable":true,"description":"Human-readable explanation of the income determination (bank income source only)"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by this applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}},"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"BankConnectionIncomeSummary":{"type":"object","description":"Income summary for a single linked bank connection","properties":{"institution_name":{"type":"string","description":"Name of the financial institution"},"accounts":{"type":"array","description":"Bank accounts on this connection used for income analysis","items":{"type":"object","description":"Account properties including name, holder names, type, and balances"}},"income":{"type":"object","description":"Aggregated income analysis for this bank connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents"},"income_streams":{"type":"array","description":"Recurring income streams identified for this bank connection","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"non_recurring":{"type":"object","description":"Non-recurring income for this bank connection","properties":{"total":{"type":"integer","description":"Total non-recurring income in cents"},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"start_date":{"type":"string","format":"date","description":"Earliest transaction date across all income streams"},"end_date":{"type":"string","format":"date","description":"Latest transaction date across all income streams"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by income transactions"}}}}},"PayrollConnectionIncomeSummary":{"type":"object","description":"Income summary for a single payroll connection","properties":{"employee_name":{"type":"string","nullable":true,"description":"Employee name as reported by the payroll provider"},"company_name":{"type":"string","nullable":true,"description":"Employer company name"},"institution_name":{"type":"string","nullable":true,"description":"Name of the payroll provider"},"company_address":{"type":"string","nullable":true,"description":"Employer address"},"title":{"type":"string","nullable":true,"description":"Job title"},"start_date":{"type":"string","nullable":true,"description":"Employment start date"},"end_date":{"type":"string","nullable":true,"description":"Employment end date (null if currently employed)"},"pay_frequency":{"type":"string","nullable":true,"description":"Pay frequency"},"pay_rate":{"type":"string","nullable":true,"description":"Pay rate description"},"pay_amount":{"type":"integer","nullable":true,"description":"Pay amount in cents"},"income":{"type":"object","nullable":true,"description":"Aggregated income analysis for this payroll connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true},"three_month_avg_monthly":{"type":"integer","nullable":true},"six_month_avg_monthly":{"type":"integer","nullable":true},"nine_month_avg_monthly":{"type":"integer","nullable":true},"twelve_month_avg_monthly":{"type":"integer","nullable":true},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"start_date":{"type":"string","format":"date","description":"Earliest paystub date"},"end_date":{"type":"string","format":"date","description":"Latest paystub date"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by paystubs"}}},"is_name_mismatched":{"type":"boolean","description":"Whether the employee name on paystubs does not match the applicant name"}}},"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"Fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}},"IncomeCriteriaResult":{"type":"object","description":"Result of evaluating a single income criteria rule","properties":{"result":{"type":"string","description":"Whether the applicant passed or failed this criteria"},"multiplier_result":{"type":"string","nullable":true,"description":"Income-to-rent multiplier result for this criteria"},"multiplier_threshold":{"type":"number","nullable":true,"description":"The multiplier threshold used in this criteria evaluation"},"criteria_used":{"type":"string","nullable":true,"description":"The specific income figure used for evaluation (e.g., which monthly average)"},"criteria_from_rule":{"type":"string","nullable":true,"description":"The rule that determined which income criteria to use"}}},"IndividualIncomeReport":{"type":"object","description":"Income report for a single applicant fetched directly. Has the same exposed fields as HouseholdIncomeReport but includes income_sources and no reports array.","properties":{"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Data timespan, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by the applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}}}}}
```

## The HouseholdIncomeReport object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"HouseholdIncomeReport":{"type":"object","description":"Combined income report aggregating data across all applicants in the group. Contains a reports array with each applicant's individual sub-report.","properties":{"reports":{"type":"array","description":"Individual income sub-reports for each applicant in the group","items":{"$ref":"#/components/schemas/ApplicantIncomeSubReport"}},"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Minimum data timespan across all applicants, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded across all applicants for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"ApplicantIncomeSubReport":{"type":"object","description":"An individual applicant's income data nested within a HouseholdIncomeReport. Contains richer per-applicant detail than the top-level individual report.","properties":{"verification_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant's income verification"},"identity":{"type":"object","description":"Identity information for this applicant","properties":{"full_name":{"type":"string"},"email":{"type":"string","format":"email"}}},"reason_completed":{"type":"string","nullable":true,"description":"Reason the verification was completed"},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RecurringIncomeData"}]},"non_recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NonRecurringIncomeData"}]},"summary_timespan_length":{"type":"integer","nullable":true,"description":"Data timespan for this applicant, in days"},"bank_connections":{"type":"array","nullable":true,"description":"Income summaries for each linked bank connection (bank income source only)","items":{"$ref":"#/components/schemas/BankConnectionIncomeSummary"}},"payroll_connections":{"type":"array","nullable":true,"description":"Income summaries for each payroll connection (payroll income source only)","items":{"$ref":"#/components/schemas/PayrollConnectionIncomeSummary"}},"income_explanation":{"type":"string","nullable":true,"description":"Human-readable explanation of the income determination (bank income source only)"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by this applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}},"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"BankConnectionIncomeSummary":{"type":"object","description":"Income summary for a single linked bank connection","properties":{"institution_name":{"type":"string","description":"Name of the financial institution"},"accounts":{"type":"array","description":"Bank accounts on this connection used for income analysis","items":{"type":"object","description":"Account properties including name, holder names, type, and balances"}},"income":{"type":"object","description":"Aggregated income analysis for this bank connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents"},"income_streams":{"type":"array","description":"Recurring income streams identified for this bank connection","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"non_recurring":{"type":"object","description":"Non-recurring income for this bank connection","properties":{"total":{"type":"integer","description":"Total non-recurring income in cents"},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"start_date":{"type":"string","format":"date","description":"Earliest transaction date across all income streams"},"end_date":{"type":"string","format":"date","description":"Latest transaction date across all income streams"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by income transactions"}}}}},"PayrollConnectionIncomeSummary":{"type":"object","description":"Income summary for a single payroll connection","properties":{"employee_name":{"type":"string","nullable":true,"description":"Employee name as reported by the payroll provider"},"company_name":{"type":"string","nullable":true,"description":"Employer company name"},"institution_name":{"type":"string","nullable":true,"description":"Name of the payroll provider"},"company_address":{"type":"string","nullable":true,"description":"Employer address"},"title":{"type":"string","nullable":true,"description":"Job title"},"start_date":{"type":"string","nullable":true,"description":"Employment start date"},"end_date":{"type":"string","nullable":true,"description":"Employment end date (null if currently employed)"},"pay_frequency":{"type":"string","nullable":true,"description":"Pay frequency"},"pay_rate":{"type":"string","nullable":true,"description":"Pay rate description"},"pay_amount":{"type":"integer","nullable":true,"description":"Pay amount in cents"},"income":{"type":"object","nullable":true,"description":"Aggregated income analysis for this payroll connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true},"three_month_avg_monthly":{"type":"integer","nullable":true},"six_month_avg_monthly":{"type":"integer","nullable":true},"nine_month_avg_monthly":{"type":"integer","nullable":true},"twelve_month_avg_monthly":{"type":"integer","nullable":true},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"start_date":{"type":"string","format":"date","description":"Earliest paystub date"},"end_date":{"type":"string","format":"date","description":"Latest paystub date"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by paystubs"}}},"is_name_mismatched":{"type":"boolean","description":"Whether the employee name on paystubs does not match the applicant name"}}},"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"Fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}},"IncomeCriteriaResult":{"type":"object","description":"Result of evaluating a single income criteria rule","properties":{"result":{"type":"string","description":"Whether the applicant passed or failed this criteria"},"multiplier_result":{"type":"string","nullable":true,"description":"Income-to-rent multiplier result for this criteria"},"multiplier_threshold":{"type":"number","nullable":true,"description":"The multiplier threshold used in this criteria evaluation"},"criteria_used":{"type":"string","nullable":true,"description":"The specific income figure used for evaluation (e.g., which monthly average)"},"criteria_from_rule":{"type":"string","nullable":true,"description":"The rule that determined which income criteria to use"}}}}}}
```

## The IdentityReportData object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"IdentityReportData":{"type":"object","description":"Identity verification report data from a completed identity verification","properties":{"outcome":{"type":"string","enum":["passed","failed"],"description":"Overall outcome of the identity verification"},"verification_types":{"type":"array","description":"Types of verification performed (e.g., government_id, selfie, tin, ecbsv)","items":{"type":"string","enum":["government_id","selfie","tin","ecbsv"]}},"checks":{"type":"array","description":"Individual verification checks performed during identity verification","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the verification check"},"identity_verification_id":{"type":"string","format":"uuid","description":"ID of the parent identity verification"},"name":{"type":"string","description":"Specific check name (e.g., id_entity_detection, selfie_liveness_detection)"},"verification_type":{"type":"string","enum":["government_id","selfie","tin","ecbsv"],"description":"Type of verification performed"},"status":{"type":"string","enum":["passed","failed","not_applicable"],"description":"Status of the verification check"},"reasons":{"type":"array","description":"Array of reason codes for check failure","items":{"type":"string"}},"metadata":{"type":"object","description":"Additional metadata about the check","nullable":true}}}}}}}}}
```

## The RecurringIncomeData object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}}}}}
```

## The NonRecurringIncomeData object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}}}}}
```

## The BankConnectionIncomeSummary object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"BankConnectionIncomeSummary":{"type":"object","description":"Income summary for a single linked bank connection","properties":{"institution_name":{"type":"string","description":"Name of the financial institution"},"accounts":{"type":"array","description":"Bank accounts on this connection used for income analysis","items":{"type":"object","description":"Account properties including name, holder names, type, and balances"}},"income":{"type":"object","description":"Aggregated income analysis for this bank connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents"},"income_streams":{"type":"array","description":"Recurring income streams identified for this bank connection","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"non_recurring":{"type":"object","description":"Non-recurring income for this bank connection","properties":{"total":{"type":"integer","description":"Total non-recurring income in cents"},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"start_date":{"type":"string","format":"date","description":"Earliest transaction date across all income streams"},"end_date":{"type":"string","format":"date","description":"Latest transaction date across all income streams"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by income transactions"}}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}}}}}
```

## The IncomeStreamProperties object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}}}}}
```

## The IncomeCriteriaResult object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"IncomeCriteriaResult":{"type":"object","description":"Result of evaluating a single income criteria rule","properties":{"result":{"type":"string","description":"Whether the applicant passed or failed this criteria"},"multiplier_result":{"type":"string","nullable":true,"description":"Income-to-rent multiplier result for this criteria"},"multiplier_threshold":{"type":"number","nullable":true,"description":"The multiplier threshold used in this criteria evaluation"},"criteria_used":{"type":"string","nullable":true,"description":"The specific income figure used for evaluation (e.g., which monthly average)"},"criteria_from_rule":{"type":"string","nullable":true,"description":"The rule that determined which income criteria to use"}}}}}}
```

## The IndividualIncomeReport object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"IndividualIncomeReport":{"type":"object","description":"Income report for a single applicant fetched directly. Has the same exposed fields as HouseholdIncomeReport but includes income_sources and no reports array.","properties":{"recurring":{"$ref":"#/components/schemas/RecurringIncomeData"},"non_recurring":{"$ref":"#/components/schemas/NonRecurringIncomeData"},"summary_timespan_length":{"type":"integer","description":"Data timespan, in days"},"criteria_rule_results":{"type":"array","nullable":true,"description":"Results of income criteria rule evaluations","items":{"$ref":"#/components/schemas/IncomeCriteriaResult"}},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"applicant_group_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant group"},"property_name":{"type":"string","nullable":true,"description":"Property name associated with the application"},"property_monthly_rent_cents":{"type":"integer","nullable":true,"description":"Property monthly rent in cents"},"created_at":{"type":"string","format":"date-time","description":"When the report was created"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by the applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}},"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeCriteriaResult":{"type":"object","description":"Result of evaluating a single income criteria rule","properties":{"result":{"type":"string","description":"Whether the applicant passed or failed this criteria"},"multiplier_result":{"type":"string","nullable":true,"description":"Income-to-rent multiplier result for this criteria"},"multiplier_threshold":{"type":"number","nullable":true,"description":"The multiplier threshold used in this criteria evaluation"},"criteria_used":{"type":"string","nullable":true,"description":"The specific income figure used for evaluation (e.g., which monthly average)"},"criteria_from_rule":{"type":"string","nullable":true,"description":"The rule that determined which income criteria to use"}}},"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"Fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}}}}}
```

## The ApplicantIncomeSubReport object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"ApplicantIncomeSubReport":{"type":"object","description":"An individual applicant's income data nested within a HouseholdIncomeReport. Contains richer per-applicant detail than the top-level individual report.","properties":{"verification_id":{"type":"string","format":"uuid","description":"Unique identifier for the applicant's income verification"},"identity":{"type":"object","description":"Identity information for this applicant","properties":{"full_name":{"type":"string"},"email":{"type":"string","format":"email"}}},"reason_completed":{"type":"string","nullable":true,"description":"Reason the verification was completed"},"income_sources":{"type":"array","description":"Income sources used for this applicant's verification","items":{"type":"object","properties":{"source":{"type":"string","enum":["bank","payroll","document"],"description":"Type of income source"}}}},"recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/RecurringIncomeData"}]},"non_recurring":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NonRecurringIncomeData"}]},"summary_timespan_length":{"type":"integer","nullable":true,"description":"Data timespan for this applicant, in days"},"bank_connections":{"type":"array","nullable":true,"description":"Income summaries for each linked bank connection (bank income source only)","items":{"$ref":"#/components/schemas/BankConnectionIncomeSummary"}},"payroll_connections":{"type":"array","nullable":true,"description":"Income summaries for each payroll connection (payroll income source only)","items":{"$ref":"#/components/schemas/PayrollConnectionIncomeSummary"}},"income_explanation":{"type":"string","nullable":true,"description":"Human-readable explanation of the income determination (bank income source only)"},"uploaded_documents":{"type":"array","nullable":true,"description":"Documents uploaded by this applicant for verification","items":{"$ref":"#/components/schemas/UploadedDocument"}}}},"RecurringIncomeData":{"type":"object","description":"Aggregated recurring income data","properties":{"total":{"type":"integer","description":"Total net recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents (null if timespan < 50 days)"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents (null if timespan < 80 days)"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents (null if timespan < 170 days)"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents (null if timespan < 260 days)"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents (null if timespan < 350 days)"},"income_streams":{"type":"array","description":"Individual recurring income streams contributing to this total","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}},"NonRecurringIncomeData":{"type":"object","description":"Aggregated non-recurring income data (no gross estimates)","properties":{"total":{"type":"integer","description":"Total net non-recurring income in cents within the summary timespan"},"one_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 1 month in cents"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net non-recurring income over 12 months in cents"},"income_streams":{"type":"array","description":"Individual non-recurring income streams","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"BankConnectionIncomeSummary":{"type":"object","description":"Income summary for a single linked bank connection","properties":{"institution_name":{"type":"string","description":"Name of the financial institution"},"accounts":{"type":"array","description":"Bank accounts on this connection used for income analysis","items":{"type":"object","description":"Account properties including name, holder names, type, and balances"}},"income":{"type":"object","description":"Aggregated income analysis for this bank connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 2 months in cents"},"three_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 3 months in cents"},"six_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 6 months in cents"},"nine_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 9 months in cents"},"twelve_month_avg_monthly":{"type":"integer","nullable":true,"description":"Average monthly net income over 12 months in cents"},"income_streams":{"type":"array","description":"Recurring income streams identified for this bank connection","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"non_recurring":{"type":"object","description":"Non-recurring income for this bank connection","properties":{"total":{"type":"integer","description":"Total non-recurring income in cents"},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}}}},"start_date":{"type":"string","format":"date","description":"Earliest transaction date across all income streams"},"end_date":{"type":"string","format":"date","description":"Latest transaction date across all income streams"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by income transactions"}}}}},"PayrollConnectionIncomeSummary":{"type":"object","description":"Income summary for a single payroll connection","properties":{"employee_name":{"type":"string","nullable":true,"description":"Employee name as reported by the payroll provider"},"company_name":{"type":"string","nullable":true,"description":"Employer company name"},"institution_name":{"type":"string","nullable":true,"description":"Name of the payroll provider"},"company_address":{"type":"string","nullable":true,"description":"Employer address"},"title":{"type":"string","nullable":true,"description":"Job title"},"start_date":{"type":"string","nullable":true,"description":"Employment start date"},"end_date":{"type":"string","nullable":true,"description":"Employment end date (null if currently employed)"},"pay_frequency":{"type":"string","nullable":true,"description":"Pay frequency"},"pay_rate":{"type":"string","nullable":true,"description":"Pay rate description"},"pay_amount":{"type":"integer","nullable":true,"description":"Pay amount in cents"},"income":{"type":"object","nullable":true,"description":"Aggregated income analysis for this payroll connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true},"three_month_avg_monthly":{"type":"integer","nullable":true},"six_month_avg_monthly":{"type":"integer","nullable":true},"nine_month_avg_monthly":{"type":"integer","nullable":true},"twelve_month_avg_monthly":{"type":"integer","nullable":true},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"start_date":{"type":"string","format":"date","description":"Earliest paystub date"},"end_date":{"type":"string","format":"date","description":"Latest paystub date"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by paystubs"}}},"is_name_mismatched":{"type":"boolean","description":"Whether the employee name on paystubs does not match the applicant name"}}},"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"Fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}}}}}
```

## The UploadedDocument object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"UploadedDocument":{"type":"object","description":"A document uploaded by the applicant (bank statement or pay stub)","properties":{"name":{"type":"string","description":"Filename of the uploaded document"},"type":{"type":"string","description":"Document type"},"fraud_risk":{"type":"string","enum":["low","needs_review","high"],"description":"Overall fraud risk assessment"},"fraud_risk_score":{"type":"integer","description":"Numerical fraud risk score (0-100, higher is riskier)"},"applicant_name":{"type":"string","nullable":true,"description":"Name of the applicant who uploaded the document"},"fraud_risk_signals":{"type":"array","description":"Fraud risk signals detected in the document","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of fraud signal detected"},"description":{"type":"string","nullable":true,"description":"Additional details about the fraud signal"}}}}}}}}}
```

## The TransactionProperties object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}}}}}
```

## The PaystubProperties object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}}}}}
```

## The PayrollConnectionIncomeSummary object

```json
{"openapi":"3.0.3","info":{"title":"PayScore API","version":"1.0.0"},"components":{"schemas":{"PayrollConnectionIncomeSummary":{"type":"object","description":"Income summary for a single payroll connection","properties":{"employee_name":{"type":"string","nullable":true,"description":"Employee name as reported by the payroll provider"},"company_name":{"type":"string","nullable":true,"description":"Employer company name"},"institution_name":{"type":"string","nullable":true,"description":"Name of the payroll provider"},"company_address":{"type":"string","nullable":true,"description":"Employer address"},"title":{"type":"string","nullable":true,"description":"Job title"},"start_date":{"type":"string","nullable":true,"description":"Employment start date"},"end_date":{"type":"string","nullable":true,"description":"Employment end date (null if currently employed)"},"pay_frequency":{"type":"string","nullable":true,"description":"Pay frequency"},"pay_rate":{"type":"string","nullable":true,"description":"Pay rate description"},"pay_amount":{"type":"integer","nullable":true,"description":"Pay amount in cents"},"income":{"type":"object","nullable":true,"description":"Aggregated income analysis for this payroll connection","properties":{"total":{"type":"integer","description":"Total net income in cents within the summary timespan"},"two_month_avg_monthly":{"type":"integer","nullable":true},"three_month_avg_monthly":{"type":"integer","nullable":true},"six_month_avg_monthly":{"type":"integer","nullable":true},"nine_month_avg_monthly":{"type":"integer","nullable":true},"twelve_month_avg_monthly":{"type":"integer","nullable":true},"income_streams":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStreamProperties"}},"start_date":{"type":"string","format":"date","description":"Earliest paystub date"},"end_date":{"type":"string","format":"date","description":"Latest paystub date"},"transaction_timespan_length":{"type":"integer","description":"Number of days covered by paystubs"}}},"is_name_mismatched":{"type":"boolean","description":"Whether the employee name on paystubs does not match the applicant name"}}},"IncomeStreamProperties":{"type":"object","description":"Properties of a single identified income stream","properties":{"name":{"type":"string","description":"Name of the income stream (typically the income source or employer)"},"total":{"type":"integer","description":"Total net amount for this income stream in cents"},"monthly_income":{"type":"integer","description":"Calculated monthly income for this stream in cents"},"start_date":{"type":"string","format":"date","description":"Start date of this income stream's period"},"end_date":{"type":"string","format":"date","description":"End date of this income stream's period"},"transactions":{"type":"array","description":"Individual transactions belonging to this income stream","items":{"$ref":"#/components/schemas/TransactionProperties"}},"paystubs":{"type":"array","description":"Paystub records for this income stream (populated for payroll sources)","items":{"$ref":"#/components/schemas/PaystubProperties"}},"pay_gap_after_transaction_indexes":{"type":"array","description":"Indexes of transactions after which an unusual pay gap was detected","items":{"type":"integer"}}}},"TransactionProperties":{"type":"object","description":"A single bank transaction within an income stream","properties":{"name":{"type":"string","description":"Transaction name or description"},"amount":{"type":"integer","description":"Transaction amount in cents"},"date":{"type":"string","description":"Transaction date formatted as MM/DD/YYYY"}}},"PaystubProperties":{"type":"object","description":"A single paystub within a payroll income stream","properties":{"gross_pay":{"type":"integer","nullable":true,"description":"Gross pay in cents"},"base_pay":{"type":"integer","nullable":true,"description":"Base pay in cents"},"bonus":{"type":"integer","nullable":true,"description":"Bonus amount in cents"},"commission":{"type":"integer","nullable":true,"description":"Commission amount in cents"},"tips":{"type":"integer","nullable":true,"description":"Tips amount in cents"},"overtime":{"type":"integer","nullable":true,"description":"Overtime pay in cents"},"other":{"type":"integer","nullable":true,"description":"Other pay in cents"},"net_pay":{"type":"integer","nullable":true,"description":"Net pay in cents"},"hours_worked":{"type":"number","nullable":true,"description":"Hours worked, rounded to 2 decimal places"},"pay_date":{"type":"string","description":"Pay date (pretty formatted)"},"start_date":{"type":"string","description":"Pay period start date (pretty formatted)"},"end_date":{"type":"string","description":"Pay period end date (pretty formatted)"}}}}}}
```