The Income-Insights report contains information on income that a user receives to their bank account(s) across all connected institutions.

Attributes

Values, data types, and descriptions for the report-level metadata in the response.

Attribute	Type	Description
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, see Link object
bank_income_summary	object	Summary of income over all accounts, see Bank Income Summary object

Link object

The information in this table is for values in the Links object.

Attribute	Type	Description
link_id	string	Unique identifier of the link
created_at	date-time	Timestamp when the link was first created
updated_at	date-time	Timestamp of the most recent update made to the link
provider	string	ID of the financial institution
provider_name	string	Name of the financial institution
tracking_info	string	Additional (optional) identifier passed by the user
accounts	array of objects	List of demand-deposit accounts connected, see Account object
bank_income_sources	array of objects	List of income sources, see Bank Income Source object

Account object

The information in this table is for values in the Accounts object.

Attribute	Type	Description
id	string	Unique identifier of the account
mask	string	The masked banking account number associated with the account
nickname	string	An alternate name for the account
type	enum	The type of account, see Account Type enum
subtype	string	The sub-type of the account
owners	array of objects	List of owners on the account, see Owner object

Owner object

The information in this table is for values in the Owner object.

Attribute	Type	Description
id	string	Unique identifier of the owner
full_name	string	Account owner's full name
email	string	Account owner's email address
phone	string	Account owner's phone number
address	object	Account owner's physical address
relation_type	string	The relationship this person has to the account

Bank Income Source object

The information in this table is for values in the Bank Income Source object.

Attribute	Type	Description
start_date	date	Earliest transaction date for this source
end_date	date	Latest transaction date for this source
account_id	string	Unique identifier of the associated account
income_description	string	A human-readable shorthand for the underlying transaction descriptions
income_category	string	The category of the income source
pay_frequency	enum	The rate at which income is deposited, see Pay Frequency enum
total_amount	string	The sum of earnings for this income source, observed over the transaction history
iso_currency_code	string	The ISO 4217 currency code for amounts in this source
transaction_count	integer	Number of income transactions for this source
historical_summary	array of objects	List of monthly summaries, see Historical Summary object
historical_average_monthly_income	string	Historical average income deposited into the account, per calendar month, typically net of taxes and deductions.
historical_average_monthly_gross_income	string	Historical average gross payment amount, per calendar month, predicted based on the transaction data.
forecasted_average_monthly_income	string	Forecasted income deposited into the account, per calendar month.
employer	object	The normalized employer for the income source, see Employer object

Historical Summary object

The information in this table is for values in the Historical summary object

Attribute	Type	Description
start_date	date	The first date of this monthly period; will be the first day of the month unless the transaction history does not go back that far
end_date	date	The last date of this monthly period; will be the first day of the month unless such date is in the future
total_amount	string	Total amount of earnings for this monthly period
iso_currency_code	string	The ISO 4217 currency code for amounts in this period
transactions	array of objects	List of transactions, see Transaction object

Transaction object

The information in this table is for values in the Transaction object

Attribute	Type	Description
transaction_id	string	Unique identifier for the transaction
amount	string	Deposit amount
iso_currency_code	string	The ISO 4217 currency code for this transaction
date	date	Date the amount was posted to the account
check_number	string	The check number for the transaction
description	string	A human-readable description for the transaction
pending	boolean	True if the status of the transaction is pending or not set

Employer object

The information in this table is for values in the Employer object

Attribute	Type	Description
id	string	Unique identifier for the employer
name	string	Name of the employer
logo_url	string	URL for the employer's logo image

Bank Income Summary object

The information in this table is for values in the Bank Income Summary object

Attribute	Type	Description
start_date	string	Earliest transaction date among all income sources
end_date	string	Latest transaction date among all income sources
income_sources_count	integer	Number of income sources for this user
income_categories_count	integer	Number of income categories for this user
income_transactions_count	integer	Number of income transactions for this user
total_amounts	array of objects	Total amount of income observed in the transaction history, over all sources. One per currency. See Total Amount object
historical_average_monthly_income	array of objects	Total monthly average income earned historically, over all sources. One per currency. See Total Amount object
historical_average_monthly_gross_income	array of objects	Total monthly average gross income earned historically, over all sources. One per currency. Gross amounts are estimated from transactions. See Total Amount object
forecasted_average_monthly_income	array of objects	Total forecasted monthly average income, over all sources. One per currency. See Total Amount object
historical_annual_gross_income	array of objects	Annualized gross income earned historically, over all sources. One per currency. See Total Amount object
historical_annual_income	array of objects	Annualized income earned historically, over all sources. One per currency. See Total Amount object
forecasted_annual_income	array of objects	Annualized forecasted income, over all sources. One per currency. See Total Amount object

Total Amount object

The information in this table is for values in the Total Amount object

Attribute	Type	Description
amount	string	Total amount
iso_currency_code	string	The ISO 4217 currency code for the amount

Enumerated Types

The following sets show the available values that an enum attribute could take

Account Type enum

Attribute	Type
CHECKING	string
SAVINGS	string
PREPAID	string

Pay Frequency enum

Attribute	Type
MONTHLY	string
SEMIMONTHLY	string
BIWEEKLY	string
WEEKLY	string
ANNUAL	string
SEMIANNUAL	string
COMMISSION	string

Endpoints

View more information about the available endpoints for Income Insights reports.

Example response

The JSON below is a sample response for the endpoint.

{
  "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": "[email protected]",
              "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"
      }
    ]
  }
}