Skip to main content
Income Insights is part of the Bank Integration verification method. It provides a comprehensive view of income received across all bank accounts connected through the verification flow, enabling detailed analysis of deposit patterns and income sources. The Income Insights report contains information on income that a user receives to their bank account(s) across all connected institutions.

​
Report-Level Attributes

​
report_id
string
Unique identifier of the report.
​
created_at
date-time
Timestamp when report was created.
​
completed_at
date-time
Timestamp when report was completed.
​
days_requested
integer
Number of days for requested transactions history.
​
links
array of objects
List of financial institutions connected.
​
bank_income_summary
object
Summary of income over all accounts.
AttributeTypeDescription
link_idstringUnique identifier of the link
created_atdate-timeTimestamp when the link was first created
updated_atdate-timeTimestamp of the most recent update
providerstringID of the financial institution
provider_namestringName of the financial institution
tracking_infostringAdditional (optional) identifier passed by user
accountsarray of objectsList of demand-deposit accounts connected
bank_income_sourcesarray of objectsList of income sources

​
Account Object

AttributeTypeDescription
idstringUnique identifier of the account
maskstringThe masked banking account number
nicknamestringAn alternate name for the account
typeenumThe type of account
subtypestringThe sub-type of the account
ownersarray of objectsList of owners on the account

​
Owner Object

AttributeTypeDescription
idstringUnique identifier of the owner
full_namestringAccount owner’s full name
emailstringAccount owner’s email address
phonestringAccount owner’s phone number
addressobjectAccount owner’s physical address
relation_typestringThe relationship this person has to the account

​
Bank Income Source Object

AttributeTypeDescription
start_datedateEarliest transaction date for this source
end_datedateLatest transaction date for this source
account_idstringUnique identifier of the associated account
income_descriptionstringHuman-readable shorthand for transaction descriptions
income_categorystringThe category of the income source
pay_frequencyenumThe rate at which income is deposited
total_amountstringSum of earnings for this income source
iso_currency_codestringThe ISO 4217 currency code
transaction_countintegerNumber of income transactions for this source
historical_summaryarray of objectsList of monthly summaries
historical_average_monthly_incomestringHistorical average income deposited per month
historical_average_monthly_gross_incomestringHistorical average gross payment amount per month
forecasted_average_monthly_incomestringForecasted income deposited per month
employerobjectThe normalized employer for the income source

​
Historical Summary Object

AttributeTypeDescription
start_datedateThe first date of this monthly period
end_datedateThe last date of this monthly period
total_amountstringTotal amount of earnings for this monthly period
iso_currency_codestringThe ISO 4217 currency code
transactionsarray of objectsList of transactions

​
Transaction Object

AttributeTypeDescription
transaction_idstringUnique identifier for the transaction
amountstringDeposit amount
iso_currency_codestringThe ISO 4217 currency code for this transaction
datedateDate the amount was posted to the account
check_numberstringThe check number for the transaction
descriptionstringA human-readable description for the transaction
pendingbooleanTrue if transaction status is pending or not set

​
Employer Object

AttributeTypeDescription
idstringUnique identifier for the employer
namestringName of the employer
logo_urlstringURL for the employer’s logo image

​
Bank Income Summary Object

AttributeTypeDescription
start_datestringEarliest transaction date among all income sources
end_datestringLatest transaction date among all income sources
income_sources_countintegerNumber of income sources for this user
income_categories_countintegerNumber of income categories for this user
income_transactions_countintegerNumber of income transactions for this user
total_amountsarray of objectsTotal income observed in transaction history
historical_average_monthly_incomearray of objectsTotal monthly average income earned historically
historical_average_monthly_gross_incomearray of objectsTotal monthly average gross income (estimated)
forecasted_average_monthly_incomearray of objectsTotal forecasted monthly average income
historical_annual_gross_incomearray of objectsAnnualized gross income earned historically
historical_annual_incomearray of objectsAnnualized income earned historically
forecasted_annual_incomearray of objectsAnnualized forecasted income

​
Total Amount Object

AttributeTypeDescription
amountstringTotal amount
iso_currency_codestringThe ISO 4217 currency code for the amount

​
Enumerated Types

​
Account Type

ValueDescription
CHECKINGChecking account
SAVINGSSavings account
PREPAIDPrepaid account

​
Pay Frequency

ValueDescription
MONTHLYMonthly payments
SEMIMONTHLYSemi-monthly payments
BIWEEKLYBi-weekly payments
WEEKLYWeekly payments
ANNUALAnnual payments
SEMIANNUALSemi-annual payments
COMMISSIONCommission-based

​
Example Response

{
  "report_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2022-05-04T11:30:00Z",
  "completed_at": "2022-05-04T12:00:00Z",
  "days_requested": 61,
  "links": [
    {
      "link_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_at": "2022-05-04T11:30:00Z",
      "updated_at": "2022-05-04T12:00:00Z",
      "provider": "Chase",
      "tracking_info": "string",
      "accounts": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "mask": "****1234",
          "nickname": "My account",
          "type": "CHECKING",
          "subtype": "MONEY_MARKET",
          "owners": [
            {
              "id": "2b623fa2fa9e49cea17d9692caa884c5",
              "full_name": "John Doe",
              "email": "john.doe@example.com",
              "phone": "14155554193",
              "address": {
                "street": "1 Morgan Ave",
                "city": "Los Angeles",
                "state": "CA",
                "zip": "90210",
                "country": "US"
              },
              "relation_type": "AUTHORIZED_USER"
            }
          ]
        }
      ],
      "bank_income_sources": [
        {
          "start_date": "2022-05-04",
          "end_date": "2022-05-04",
          "account_id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "income_description": "Paycheck",
          "income_category": "Income: Paycheck",
          "pay_frequency": "SM",
          "total_amount": "200.31",
          "iso_currency_code": "USD",
          "transaction_count": 1,
          "historical_summary": [
            {
              "start_date": "2022-05-04",
              "end_date": "2022-05-04",
              "total_amount": "200.31",
              "iso_currency_code": "USD",
              "transactions": [
                {
                  "amount": "200.31",
                  "iso_currency_code": "USD",
                  "date": "2022-05-04",
                  "check_number": "string",
                  "description": "string",
                  "pending": true,
                  "transaction_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
                }
              ]
            }
          ],
          "historical_average_monthly_income": "10000.00",
          "historical_average_monthly_gross_income": "12000.00",
          "forecasted_average_monthly_income": "10000.00",
          "employer": {
            "id": "meta",
            "name": "Meta",
            "logo_url": "string"
          }
        }
      ]
    }
  ],
  "bank_income_summary": {
    "start_date": "2022-05-04",
    "end_date": "2022-05-04",
    "income_sources_count": 1,
    "income_categories_count": 1,
    "income_transactions_count": 1,
    "total_amounts": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ],
    "historical_average_monthly_gross_income": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ],
    "historical_average_monthly_income": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ],
    "forecasted_average_monthly_income": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ],
    "historical_annual_gross_income": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ],
    "historical_annual_income": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ],
    "forecasted_annual_income": [
      {
        "amount": "200.31",
        "iso_currency_code": "USD"
      }
    ]
  }
}

​
Endpoints