> ## 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 User Income Insights object > Find more information on data returned by the user-level Income Insights report. 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](#link-object) | | bank\_income\_summary | object | Summary of income over all accounts, see [Bank Income Summary object](#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](#account-object) | | bank\_income\_sources | array of objects | List of income sources, see [Bank Income Source object](#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](#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) | *** ## 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](#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](#income-category-enum) | | pay\_frequency | enum | The rate at which income is deposited, see [Pay Frequency enum](#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-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](#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) | *** ## 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](#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](#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](#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](#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](#total-amount-object) | | historical\_annual\_income | array of objects | Annualized income earned historically, over all sources. One per currency. See [Total Amount object](#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) | *** ## 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. * [Create an income-insights report](/api-reference/income-insights/income-insights-report-create) * [Retrieve an income-insights report](/api-reference/income-insights/income-insights-report-retrieve) # Example response The JSON below is a sample response for the endpoint. ```json theme={null} { "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" } ] } } ```