--- title: "Create a user bank income insights report" method: POST path: "/v1/users/{user_id}/income_insights/reports/" tags: ["Income Insights Reports"] --- # Create a user bank income insights report `POST /v1/users/{user_id}/income_insights/reports/` ## Request - Base URL: `https://prod.truv.com` - URL: `https://prod.truv.com/v1/users/{user_id}/income_insights/reports/` - Auth: API key in header `X-Access-Client-Id` and API key in header `X-Access-Secret` The endpoint creates a bank income insights report for the user. ## Request body - IncomeInsightsRequest: Income insights report parameters. - `days_requested` integer, required: The specific duration in days for which the report is requested to be generated. - `consumer_report_permissible_purpose` 'ACCOUNT_REVIEW_CREDIT' | 'ACCOUNT_REVIEW_NON_CREDIT' | 'EMPLOYMENT' | 'EXTENSION_OF_CREDIT' | 'LEGITIMATE_BUSINESS_NEED_TENANT_SCREENING' | 'LEGITIMATE_BUSINESS_NEED_OTHER' | 'WRITTEN_INSTRUCTION_PREQUALIFICATION' | 'WRITTEN_INSTRUCTION_OTHER': Describes the reason you are generating an Income Insights Report for this user. ## Response `201` - IncomeInsightsApplicantReport - `report_id` string, required: Unique identifier of the report. - `created_at` string, date-time, required: Timestamp when the report was created. - `completed_at` string, date-time, required: Timestamp when the report was completed. - `days_requested` integer, required: Number of days for which transactions are requested. - `links` LinkIncomeInsights[], required: List of assets links - `link_id` string, required: Unique identifier of the link. - `created_at` string, date-time: The date and time when the link was first created, specified in ISO 8601 format. - `updated_at` string, date-time: The date and time of the most recent update made to the link, in ISO 8601 format. - `provider` string: Data provider ID. - `provider_name` string: Data provider name. - `tracking_info` string, nullable: Additional optional identifier passed by user. - `accounts` AccountIncomeInsights[], required: List of demand deposit accounts. - `id` string, required: Unique identifier of the account. - `mask` string, nullable: The masked banking account number associated with a particular account. - `nickname` string, nullable: An alternate name for the account. - `type` string: The parent type of the account, e.g., CHECKING or SAVINGS. - `subtype` string, nullable: The account's subtype, e.g., PLAN_401_K, MONEY_MARKET, or HOME_EQUITY. - `days_available` integer: Days of transaction history available at report generation time, from earliest transaction to report date (inclusive). - `owners` AssetsOwner[], required: List of owners for account. - `id` string, string, required: Unique identifier of the owner. - `full_name` string: The account owner's name. - `email` string, email, nullable: The account owner's email address. - `phone` string, nullable: The account owner's phone number. - `address` object: The account owner's address. - `street` string, nullable: Street address as provided by the financial institution. May contain multiple lines separated by `\n`. - `city` string, nullable: City as provided by the financial institution. - `state` string, nullable: State or region. For US addresses this is typically a 2-letter state code; returned as provided by the financial institution. - `zip` string, nullable: Postal code as provided by the financial institution. Typically a 5-digit US ZIP code; ZIP+4, 9 digits without a separator, and non-US postal codes also occur. - `country` string, nullable: 2-letter ISO 3166-1 alpha-2 country code. Defaults to `US` when the source does not specify a country. - `relation_type` 'PRIMARY' | 'BUSINESS' | 'JOINT' | 'SECONDARY' | 'AUTHORIZED_USER' | 'FOR_BENEFIT_OF' | 'ACCOUNT_BENEFICIARY' | 'CUSTODIAN' | 'OTHER' | 'null', nullable: The relationship this person has to the account. - `bank_income_sources` BankIncomeInsightsSource[]: List of bank income sources. - `start_date` string, date, required: Minimum of all dates within the specific income sources in the user's bank account for days requested by the client. - `end_date` string, date, required: Maximum of all dates within the specific income sources in the user's bank account for days requested by the client. - `account_id` string, required: Unique identifier of the account. - `income_description` string: Description for the underlying income transactions. - `income_category` 'PAYCHECK' | 'RETIREMENT' | 'RENTAL' | 'UNEMPLOYMENT' | 'GOVERNMENT_EMPLOYMENT' | 'GOVERNMENT_BENEFITS' | 'PRIVATE_BENEFITS' | 'EWA_PAYROLL' | 'GIG_ECONOMY' | 'P2P_TRANSFER' | 'TAX_CREDITS' | 'CASH_OR_CHECK' | 'INTEREST' | 'INVESTMENT' | 'OTHER' | 'null', nullable: The income category. - `pay_frequency` 'M' | 'SM' | 'W' | 'BW' | 'A' | 'SA' | 'C' | 'null', nullable: Pay frequency: * `M` - Monthly, * `SM` - Semi-Monthly, * `W` - Weekly, * `BW` - Bi-Weekly, * `A` - Annually, * `SA` - Semiannually, * `C` - Commission - `next_payment_date` string, date, nullable: The next payment date for the income source. - `total_amount` string, decimal, required: Total amount of earnings for the income source of the user in the summary. - `iso_currency_code` string, nullable: The ISO 4217 currency code of the amount or balance. - `transaction_count` integer, required: Number of income transactions per end user for this source. - `historical_summary` object[], required: List of bank statements for each period. - `start_date` string, date: The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. - `end_date` string, date: The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. - `total_amount` string, decimal: Total amount of earnings for the income source of the user for the month in the summary. - `iso_currency_code` string, nullable: The ISO 4217 currency code of the amount or balance. - `transactions` object[]: List of transactions - `amount` string, decimal: The settled value of the transaction, denominated in the transactions's currency as stated in iso_currency_code. Negative values when money moves out of the account; positive otherwise. - `iso_currency_code` string, nullable: The ISO 4217 currency code of the amount or balance. - `date` string, date: The date that the transaction occurred. - `check_number` string, nullable: The check number for the transaction. - `description` string: A human-readable transaction description. - `pending` boolean: True if status of the transaction is PENDING or not set. - `transaction_id` string: Unique identifier of the transaction. - `historical_average_monthly_income` string, decimal, nullable: Historical average income deposited into the account, per calendar month, typically net of taxes and deductions. - `historical_average_monthly_gross_income` string, decimal, nullable: Historical average gross payment amount, per calendar month, predicted based on the transaction data. - `forecasted_average_monthly_income` string, decimal, nullable: Forecasted income deposited into the account, per calendar month. - `avg_deposit_amount` string, decimal, required: The average amount received per deposit, typically net of taxes and deductions. - `avg_gross_deposit_amount` string, decimal: The average gross payment per deposit. Gross pay is predicted based on the transaction data. - `employer` Employer, nullable - `id` string, nullable, required: Employer ID. - `name` string, required: Employer name. - `logo_url` string, nullable: Employer logo image. - `bank_income_summary` BankIncomeInsightsSourcesSummary, required - `start_date` string, date, nullable, required: Minimum of all transaction dates among all income sources in the user's bank accounts for days requested by the client. - `end_date` string, date, nullable, required: Maximum of all transaction dates among all income sources in the user's bank accounts for days requested by the client. - `income_sources_count` integer, nullable, required: Number of income sources per end user. - `income_categories_count` integer, nullable, required: Number of income categories per end user. - `income_transactions_count` integer, nullable, required: Number of income transactions per end user. - `total_amounts` AmountISOCurrency[], required: Total amount of income earned, over all sources. One per currency. - `amount` string, decimal, required: Amount of earnings. - `iso_currency_code` string, nullable, required: The ISO 4217 currency code of the amount or balance. - `historical_average_monthly_gross_income` AmountISOCurrency[], required: Total monthly average gross income earned historically, over all sources. One per currency. Gross amounts are estimated from transactions. - `amount` string, decimal, required: Amount of earnings. - `iso_currency_code` string, nullable, required: The ISO 4217 currency code of the amount or balance. - `historical_average_monthly_income` AmountISOCurrency[], required: Total monthly average income earned historically, over all sources. One per currency. - `amount` string, decimal, required: Amount of earnings. - `iso_currency_code` string, nullable, required: The ISO 4217 currency code of the amount or balance. - `forecasted_average_monthly_income` AmountISOCurrency[], required: Total forecasted monthly average income, over all sources. One per currency. - `amount` string, decimal, required: Amount of earnings. - `iso_currency_code` string, nullable, required: The ISO 4217 currency code of the amount or balance. - `historical_annual_gross_income` AmountISOCurrency[], required: Annualized gross income earned historically, over all sources. One per currency. - `amount` string, decimal, required: Amount of earnings. - `iso_currency_code` string, nullable, required: The ISO 4217 currency code of the amount or balance. - `historical_annual_income` AmountISOCurrency[], required: Annualized income earned historically, over all sources. One per currency. - `amount` string, decimal, required: Amount of earnings. - `iso_currency_code` string, nullable, required: The ISO 4217 currency code of the amount or balance. - `forecasted_annual_income` AmountISOCurrency[], required: Annualized forecasted income, over all sources. One per currency. - `amount` string, decimal, required: Amount of earnings. - `iso_currency_code` string, nullable, required: The ISO 4217 currency code of the amount or balance. ## Other responses - `400`: HTTP 400 Bad Request - `401`: HTTP 401 Unauthorized - `403`: HTTP 403 Forbidden ## Changes - **2026-07-27** `f7c013875516`: 15 info - the `bank_income_summary/forecasted_annual_income/items/amount` response's property pattern `^-?\d{1,10}\.\d{2}$` was added for the status `201` - the `bank_income_summary/forecasted_average_monthly_income/items/amount` response's property pattern `^-?\d{1,10}\.\d{2}$` was added for the status `201` - the `bank_income_summary/historical_annual_gross_income/items/amount` response's property pattern `^-?\d{1,10}\.\d{2}$` was added for the status `201` - the `bank_income_summary/historical_annual_income/items/amount` response's property pattern `^-?\d{1,10}\.\d{2}$` was added for the status `201` - …11 more - **2026-07-26** `e58688835e25`: 5 breaking - the response property `bank_income_summary/income_categories_count` became nullable for the status `201` - the response property `bank_income_summary/income_sources_count` became nullable for the status `201` - the response property `bank_income_summary/income_transactions_count` became nullable for the status `201` - the response property `links/items/accounts/items/mask` became nullable for the status `201` - …1 more [Operation history](https://skmtc.dev/truv/apis/truv-api/changes/v1/users/:user_id/income_insights/reports/post.md) --- [API](https://skmtc.dev/truv/apis/truv-api.md) - [All operations](https://skmtc.dev/truv/apis/truv-api/llms.txt) - [OpenAPI document](https://skmtc.dev/truv/apis/truv-api/revisions/e20fd88e9371?raw)