Skip to main content
Verify income by connecting to the applicant’s bank account and analyzing transaction history. Truv generates an income insights report from deposit patterns, giving you income data even when payroll connections are unavailable.
Integration pattern: Bridge Widget | Products: Income Insights | Demo: Bank Income

​
Get started

1

Run the demo

Clone and run the Bank Income demo to see the full bank income verification flow working locally.
Open http://localhost:5173, select Consumer Credit > Bank Income, and walk through a verification using sandbox credentials (goodlogin / goodpassword).See full setup instructions for ngrok and environment configuration.
2

Understand the API flow

The demo follows this sequence:
  1. Search for financial institution — Your server calls GET /v1/providers/ with data_source=financial_accounts to find the applicant’s bank. The response returns a provider_id.
  2. Create a user — Your server calls POST /v1/users/ to create a Truv user.
  3. Create a bridge token — Your server calls POST /v1/users//tokens/ with product_type: "income", data_sources: ["financial_accounts"], and optionally provider_id to deeplink Bridge to the bank.
  4. Initialize Bridge — Your frontend opens Truv Bridge with the bridge_token. The applicant connects their bank account.
  5. Receive webhooks — Truv sends a task-status-updated webhook when verification completes. Verify the signature using the X-Webhook-Sign header with HMAC-SHA256.
  6. Retrieve the income insights report — Fetch the report with POST /v1/users//income_insights/reports/. The report contains income derived from bank transaction analysis.
3

Review the code

Each step maps to a specific file in the demo. Use these as reference when building your integration.

​
Consumer Credit-specific configuration

​
Bridge token for bank income

Set data_sources to ["financial_accounts"] to restrict Bridge to bank connections only:
Pass provider_id from the providers search to deeplink Bridge directly to the bank. Without it, Bridge shows its own institution search.
Bank income uses provider_id (not company_mapping_id). The company_mapping_id field is for payroll employers. Passing the wrong identifier type causes Bridge to show a generic search screen.

​
Income insights report

Bank income verification returns an income insights report instead of a standard VOIE report. Income insights are derived from transaction patterns rather than payroll data. The report includes:
  • Estimated annual income
  • Income streams and frequency
  • Transaction-level detail

​
How bank income differs from payroll VOIE

Bank income analyzes deposit transactions in the applicant’s bank account to derive income. It does not connect to payroll systems. This means the data shape and coverage differ significantly from a standard payroll income verification.

​
Data comparison

​
Report structure notes

  • The bank_income_summary arrays are structured to support multiple currencies, but in practice contain only USD entries.
  • Fields standard to payroll VOIE that are always null in bank income responses: w2s, bank_accounts under employments, and standard payroll deduction line items.
  • Income amounts are derived estimates, not exact figures from pay stubs.

​
When to use bank income vs payroll

For the most complete income picture, include both income and assets products in your order. The income product captures payroll-connected employment, while assets with data_sources: ["financial_accounts"] enables bank income analysis. The applicant connects both in a single Bridge session.

​
Next steps

Smart Routing

Automatically recommend the best method based on employer coverage

Payroll Income

Verify income directly from payroll for higher data quality

Bridge Widget Guide

Full implementation guide for user creation, bridge tokens, and Bridge initialization

Income Insights API

Full API reference for income insights reports