> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Bank Income Report Object

> Find more information about bank income reports.

# Attributes

The table below has the values and descriptions of the bank income report responses.

| Attribute       | Type             | Description                                                                                                                       |
| :-------------- | :--------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| status          | string           | Status of report, possible values `success`, `processing`                                                                         |
| completed\_at   | date-time        | Time when report was completed                                                                                                    |
| days\_requested | int32            | Requested number of days for specified transactions                                                                               |
| tracking\_info  | string           | Additional optional identifier passed by user                                                                                     |
| provider        | string           | Data provider identifier                                                                                                          |
| access\_token   | string           | Access token of existing Link                                                                                                     |
| companies       | array of strings | List of companies person works for                                                                                                |
| accounts        | array of objects | List of bank accounts, see [Accounts object](#accounts-object)                                                                    |
| income          | array of objects | List of bank income sources, see [Income object](#income-object)                                                                  |
| summary         | object           | Bank account information summary, see [Summary object](#summary-object)                                                           |
| is\_suspicious  | Boolean          | Status of data from source marked as suspicious, such as if detecting fraud in uploaded documents or user SSN does not match data |

## Accounts object

The values in this table are for the Accounts object.

| Attribute   | Type             | Description                                                             |
| :---------- | :--------------- | :---------------------------------------------------------------------- |
| id          | string           | Unique identifier of account                                            |
| created\_at | date-time        | Date and time when account was created in Truv                          |
| updated\_at | date-time        | Date and time when account was last updated in Truv                     |
| type        | string           | Parent type of account, example `CHECKING` or `SAVINGS`                 |
| subtype     | string           | Account subtype, example `PLAN_401_K`, `MONEY_MARKET`, or `HOME_EQUITY` |
| mask        | string           | Masked banking account number associated with specific account          |
| nickname    | string           | Alternate account name                                                  |
| owners      | array of objects | List of account's owners                                                |

## Owner object

The values in this table are for the Owner object.

| Attribute      | Type   | Description                          |
| :------------- | :----- | :----------------------------------- |
| id             | string | Unique identifier of the owner       |
| full\_name     | string | Full name of the owner               |
| email          | string | Email of the owner                   |
| phone          | string | Phone of the owner                   |
| address        | object | Address of the owner                 |
| relation\_type | string | Relation of the owner to the account |

## Income object

This table contains the attributes in the Income object.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Attribute
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        start\_date
      </td>

      <td>
        date
      </td>

      <td>
        Minimum of all dates within specific income sources in user bank accounts for days requested by client
      </td>
    </tr>

    <tr>
      <td>
        end\_date
      </td>

      <td>
        date
      </td>

      <td>
        Maximum of all dates within specific income sources in user bank accounts for days requested by client
      </td>
    </tr>

    <tr>
      <td>
        account\_id
      </td>

      <td>
        string
      </td>

      <td>
        Unique identifier of account
      </td>
    </tr>

    <tr>
      <td>
        income\_description
      </td>

      <td>
        string
      </td>

      <td>
        Original description for underlying income transactions
      </td>
    </tr>

    <tr>
      <td>
        income\_category
      </td>

      <td>
        string
      </td>

      <td>
        Income category, see [Income categories](#income-categories) for possible values and gross-up details
      </td>
    </tr>

    <tr>
      <td>
        avg\_deposit\_amount
      </td>

      <td>
        number
      </td>

      <td>
        The average amount received per deposit, typically net of taxes and deductions
      </td>
    </tr>

    <tr>
      <td>
        avg\_gross\_deposit\_amount
      </td>

      <td>
        number
      </td>

      <td>
        The average gross payment per deposit. Gross pay is predicted based on the transaction data
      </td>
    </tr>

    <tr>
      <td>
        pay\_frequency
      </td>

      <td>
        string
      </td>

      <td>
        Frequency of direct deposit posted into bank account, see values below

        `M` - Monthly\
        `SM` - Semi-monthly\
        `W` - Weekly\
        `BW` - Bi-weekly\
        `A` - Annually\
        `SA` - Semi-annually\
        `C`- Commission
      </td>
    </tr>

    <tr>
      <td>
        next\_payment\_date
      </td>

      <td>
        date
      </td>

      <td>
        The next payment date for the income source
      </td>
    </tr>

    <tr>
      <td>
        total\_amount
      </td>

      <td>
        number
      </td>

      <td>
        Total amount of earnings for the income source of the user in the summary
      </td>
    </tr>

    <tr>
      <td>
        iso\_currency\_code
      </td>

      <td>
        string
      </td>

      <td>
        The ISO 4217 currency code of the amount or balance
      </td>
    </tr>

    <tr>
      <td>
        transaction\_count
      </td>

      <td>
        integer
      </td>

      <td>
        Number of income transactions per end user for specific source
      </td>
    </tr>

    <tr>
      <td>
        historical\_summary
      </td>

      <td>
        array of objects
      </td>

      <td>
        List of bank statements for each period, see [Historical summary object](#historical-summary-object)
      </td>
    </tr>
  </tbody>
</Table>

### Income categories

Each income source in the report is assigned one of the following categories. For categories that support gross-up, `avg_gross_deposit_amount` contains the estimated gross payment before taxes and deductions. For categories without gross-up, `avg_gross_deposit_amount` equals `avg_deposit_amount`.

| Category              | Value                   | Grossed up |
| :-------------------- | :---------------------- | :--------- |
| Paycheck              | `PAYCHECK`              | Yes        |
| Retirement            | `RETIREMENT`            | Yes        |
| Government Employment | `GOVERNMENT_EMPLOYMENT` | Yes        |
| EWA Payroll           | `EWA_PAYROLL`           | Yes        |
| Gig Economy           | `GIG_ECONOMY`           | No         |
| Government Benefits   | `GOVERNMENT_BENEFITS`   | No         |
| Rental                | `RENTAL`                | No         |
| Unemployment          | `UNEMPLOYMENT`          | No         |
| Private Benefits      | `PRIVATE_BENEFITS`      | No         |
| Cash or Check         | `CASH_OR_CHECK`         | No         |
| Tax Credits           | `TAX_CREDITS`           | No         |
| P2P Transfer          | `P2P_TRANSFER`          | No         |

### Historical summary object

The table below contains the attributes from the Historical summary object.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Attribute
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        start\_date
      </td>

      <td>
        date
      </td>

      <td>
        Start date of period covered in specific monthly summary, value is set to first day of month unless covered month is partial\
        *NOTE: Partial months are the first month included in the summary when the requested date range does not begin with the first day of the month.*
      </td>
    </tr>

    <tr>
      <td>
        end\_date
      </td>

      <td>
        date
      </td>

      <td>
        End date of period included in specific monthly summary, value is set to last day of the month unless covered month is partial\
        *NOTE: Partial months are the last month included in the summary when the requested date range does not end with the last day of the month.*
      </td>
    </tr>

    <tr>
      <td>
        total\_amount
      </td>

      <td>
        number
      </td>

      <td>
        Total amount of earnings for the income source of the user for the month in the summary
      </td>
    </tr>

    <tr>
      <td>
        iso\_currency\_code
      </td>

      <td>
        string
      </td>

      <td>
        The ISO 4217 currency code of the amount or balance
      </td>
    </tr>

    <tr>
      <td>
        transactions
      </td>

      <td>
        array of objects
      </td>

      <td>
        List of transactions, see [Transactions object](#transactions-object)
      </td>
    </tr>
  </tbody>
</Table>

### Transactions object

View information about the attributes in the Income object below.

| Attribute           | Type    | Description                                                                                                                                                                 |
| :------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount              | string  | Settled value of transaction, denominated in transactions currency as stated in `iso_currency_code`, positive value when money moves out of account and negative otherwise. |
| iso\_currency\_code | string  | ISO 4217 currency code of amount or balance                                                                                                                                 |
| date                | date    | Date transaction occurred                                                                                                                                                   |
| check\_number       | string  | Check number for transaction                                                                                                                                                |
| description         | string  | Human-readable transaction description                                                                                                                                      |
| pending             | Boolean | Status of transaction as pending or not set                                                                                                                                 |
| transaction\_id     | string  | Unique identifier of transaction                                                                                                                                            |

## Summary object

View information about the attributes in the Summary object below.

| Attribute                   | Type    | Description                                                                                    |
| :-------------------------- | :------ | :--------------------------------------------------------------------------------------------- |
| start\_date                 | date    | Minimum of all dates between income sources in user bank accounts for days requested by client |
| end\_date                   | date    | Maximum of all dates between income sources in user bank accounts for days requested by client |
| income\_sources\_count      | integer | Number of income sources per end user                                                          |
| income\_categories\_count   | integer | Number of income categories per end user                                                       |
| income\_transactions\_count | integer | Number of income transactions per end user                                                     |
| total\_amount               | string  | Total amount of earnings for user income in summary                                            |
| iso\_currency\_code         | string  | ISO 4217 currency code of amount or balance                                                    |

# Endpoints

View more information about the available endpoints below.

* [Retrieves a bank income report](/api-reference/bank-income-insights/bank-income-report-retrieve)

# Example response

The JSON sample below is from the bank income response.

```json theme={null}
{
    "access_token": "a1685cadf2fe4e179cf883d2c166efd0",
    "accounts": [
        {
            "created_at": "2024-11-25T15:46:30.668062Z",
            "id": "3aed25abdbc246138b84a2afd46cb05b",
            "mask": "******0685",
            "nickname": null,
            "owners": [
                {
                    "address": {
                        "city": "Redwood City",
                        "country": null,
                        "state": "CA",
                        "street": "35 Dry Ridge Rd",
                        "zip": "94062"
                    },
                    "email": "john.doe@example.com",
                    "full_name": "John Doe",
                    "id": "a43909f402f84f2392257d1e6eaf715b",
                    "phone": "14155554193",
                    "relation_type": null
                }
            ],
            "subtype": null,
            "type": "CHECKING",
            "updated_at": "2024-11-25T15:46:30.668073Z"
        }
    ],
    "companies": [
        "string"
    ],
    "completed_at": "2024-11-25T15:46:47.498456Z",
    "days_requested": 61,
    "income": [
        {
            "account_id": "3aed25abdbc246138b84a2afd46cb05b",
            "avg_deposit_amount": "1327.84",
            "avg_gross_deposit_amount": "1765.19",
            "end_date": "2024-11-24",
            "historical_summary": [
                {
                    "end_date": "2024-09-30",
                    "iso_currency_code": "USD",
                    "start_date": "2024-09-25",
                    "total_amount": "1327.84",
                    "transactions": [
                        {
                            "amount": "1327.84",
                            "check_number": null,
                            "date": "2024-09-27",
                            "description": "string",
                            "iso_currency_code": "USD",
                            "pending": false,
                            "transaction_id": "c08230e3b20c4cd0b319bc5c3062ae1d"
                        }
                    ]
                },
                {
                    "end_date": "2024-10-31",
                    "iso_currency_code": "USD",
                    "start_date": "2024-10-01",
                    "total_amount": "2655.68",
                    "transactions": [
                        {
                            "amount": "1327.84",
                            "check_number": null,
                            "date": "2024-10-11",
                            "description": "string",
                            "iso_currency_code": "USD",
                            "pending": false,
                            "transaction_id": "a9b3aee936e04e6788af36c467206d29"
                        },
                        {
                            "amount": "1327.84",
                            "check_number": null,
                            "date": "2024-10-25",
                            "description": "string",
                            "iso_currency_code": "USD",
                            "pending": false,
                            "transaction_id": "4c262810f0534067b4f86fa76873a5f8"
                        }
                    ]
                },
                {
                    "end_date": "2024-11-24",
                    "iso_currency_code": "USD",
                    "start_date": "2024-11-01",
                    "total_amount": "2655.68",
                    "transactions": [
                        {
                            "amount": "1327.84",
                            "check_number": null,
                            "date": "2024-11-08",
                            "description": "string",
                            "iso_currency_code": "USD",
                            "pending": false,
                            "transaction_id": "1d1c70529fb940918bcabbb235216679"
                        },
                        {
                            "amount": "1327.84",
                            "check_number": null,
                            "date": "2024-11-22",
                            "description": "string",
                            "iso_currency_code": "USD",
                            "pending": false,
                            "transaction_id": "67e88c96515c40d29e454bb27d407406"
                        }
                    ]
                }
            ],
            "income_category": "PAYCHECK",
            "income_description": "string",
            "iso_currency_code": "USD",
            "pay_frequency": "BW",
            "start_date": "2024-09-25",
            "total_amount": "6639.20",
            "transaction_count": 5
        }
    ],
    "is_suspicious": false,
    "provider": "9f732f7a-b6e2-4c60-81eb-af6274f411dc",
    "status": "success",
    "summary": {
        "end_date": "2024-11-24",
        "income_categories_count": 1,
        "income_sources_count": 1,
        "income_transactions_count": 5,
        "iso_currency_code": "USD",
        "start_date": "2024-09-25",
        "total_amount": "6639.20"
    },
    "tracking_info": null
}
```