The Income Insights report analyzes transaction data across a user’s connected bank accounts to detect income sources, calculate averages, and forecast future income.

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
days_available	integer	Days of transaction history available at report generation time, from earliest transaction to report date (inclusive)
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

Income source qualification

Truv groups a user’s deposits into candidate sources and then decides which to surface as bank_income_source entries. Patterns that don’t qualify still appear in the underlying transactions; they’re just not surfaced as an income source. Two checks gate the decision:

Check	Rule
Recurring	A pay frequency is detected — weekly, bi-weekly, semi-monthly, or monthly
Current	The most recent deposit is no more than 3 pay periods old

In practice a qualifying source needs at least 3 deposits. The “≥3” floor isn’t a separate gate — it’s enforced upstream by the employer-grouping step and by the pay-frequency model, both of which require at least 3 transactions before they’ll emit a result. When the source-level total and per-period average are computed, major outlier deposits are trimmed (IQR filter). This shapes the published averages but is not a qualification check — a noisy source is still surfaced.

These rules describe regular income. Irregular categories — GIG_ECONOMY, RENTAL, EWA_PAYROLL, P2P_TRANSFER, TAX_CREDITS, CASH_OR_CHECK — skip the Recurring check and use a relaxed Current tolerance (2 months). See the Income category enum for the full list.

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, see Income Category enum
pay_frequency	enum	The rate at which income is deposited, see Pay Frequency enum
next_payment_date	date	The next payment date for the income source
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.
avg_deposit_amount	string	The average amount received per deposit, typically net of taxes and deductions
avg_gross_deposit_amount	string	The average gross payment per deposit. Gross pay is predicted based on the transaction data
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. The income_category and pay_frequency fields are nullable and may return null.

Account type enum

Attribute	Type
CHECKING	string
SAVINGS	string
PREPAID	string

Income category enum

Value	Description	Grossed up
PAYCHECK	Regular paycheck deposits	Yes
RETIREMENT	Retirement income	Yes
GOVERNMENT_EMPLOYMENT	Government employment income	Yes
EWA_PAYROLL	Earned wage access payroll	Yes
GIG_ECONOMY	Gig economy income	No
GOVERNMENT_BENEFITS	Government benefits	No
RENTAL	Rental income	No
UNEMPLOYMENT	Unemployment benefits	No
PRIVATE_BENEFITS	Private benefits	No
CASH_OR_CHECK	Cash or check deposits	No
TAX_CREDITS	Tax credit payments	No
P2P_TRANSFER	Peer-to-peer transfers	No
INTEREST	Interest income	No
INVESTMENT	Investment income	No
OTHER	Other income	No

Pay frequency enum

Value	Pay frequency
`M`	Monthly
`SM`	Semi-Monthly
`W`	Weekly
`BW`	Bi-Weekly
`A`	Annually
`SA`	Semiannually
`C`	Commission

Permissible purpose enum

A permissible purpose is required when creating an Income Insights report, passed in the consumer_report_permissible_purpose field. It identifies why you are requesting the consumer’s financial data.

Value	Use case
`ACCOUNT_REVIEW_CREDIT`	Reviewing an existing credit account
`ACCOUNT_REVIEW_NON_CREDIT`	Reviewing an existing non-credit account
`EMPLOYMENT`	Employment verification
`EXTENSION_OF_CREDIT`	Evaluating a credit application
`LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING`	Tenant screening
`LEGITIMATE_BUSINESS_NEED_OTHER`	Other legitimate business need
`WRITTEN_INSTRUCTION_PREQUALIFICATION`	Prequalification with written consent
`WRITTEN_INSTRUCTION_OTHER`	Other use with written consent

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",
      "provider_name": "Chase Bank",
      "tracking_info": "string",
      "accounts": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "mask": "****1234",
          "nickname": "My account",
          "type": "CHECKING",
          "subtype": "MONEY_MARKET",
          "days_available": 365,
          "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": "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",
          "next_payment_date": "2022-06-01",
          "avg_deposit_amount": "5000.00",
          "avg_gross_deposit_amount": "6000.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"
      }
    ]
  }
}

​Attributes

​Link object

​Account object

​Owner object

​Income source qualification

​Bank income source object

​Historical summary object

​Transaction object

​Employer object

​Bank Income Summary object

​Total amount object

​Enumerated Types

​Account type enum

​Income category enum

​Pay frequency enum

​Permissible purpose enum

​Endpoints

​Example response

Attributes

Link object

Account object

Owner object

Income source qualification

Bank income source object

Historical summary object

Transaction object

Employer object

Bank Income Summary object

Total amount object

Enumerated Types

Account type enum

Income category enum

Pay frequency enum

Permissible purpose enum

Endpoints

Example response