# Getting the Report Data
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
`GET` `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` | The net income to rent multiplier of the applicant. This is calculated by comparing the applicant's recurring 3 month average monthly net income with the monthly rent. When this value is not available (when the summary\_timespan\_length<80 days), we use the recurring 2 month average monthly net income.
When the 2 month average monthly value is not available (summary\_timespan\_length 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 monthly\_rent is not provided when creating the screening request.
|
| `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[]` | The calculated results per each income criteria that your organization has configured.
If this is set, income\_multiplier\_result will be "unavailable" and income\_multiplier will be null.
|
| `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.
{% 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
{
"reports": [
{
"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"
}
### 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` | Has the value of the criteria used in the calculation of the report data. See below section.
If a fallback criteria was configured and used when the prior criteria data in the report was unavailable, then it will be shown here.
If all criteria were unavailable for the report, the first criteria will be shown.
|
#### 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"
}
]
}
```