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: BankIncome

​
Get started

1

Run the demo

Clone and run the BankIncome demo to see the full bank income verification flow working locally.
git clone https://github.com/truvhq/demo-apps.git
cd demo-apps
npm install && npm start
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.
StepDemo fileAPI reference
Institution searchsrc/components/CompanySearch.jsxProviders List
User creationserver/routes/bridge.jsPOST /v1/users/
Bridge tokenserver/routes/bridge.jsPOST /v1/users//tokens/
Bridge initializationsrc/demos/BankIncome.jsxBridge SDK
Webhook verificationserver/webhooks.jsWebhook events
Report retrievalserver/routes/user-reports.jsIncome Insights Report

​
Consumer Credit-specific configuration

​
Bridge token for bank income

Set data_sources to ["financial_accounts"] to restrict Bridge to bank connections only: 
{
  "product_type": "income",
  "data_sources": ["financial_accounts"],
  "provider_id": "PROVIDER_ID"
}
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

Data pointPayroll VOIEBank income
Income amountExact gross/net from paystubsEstimated from deposit patterns
Employer nameFrom payroll providerNot available (inferred from transaction descriptions)
Pay frequencyExact (BW, SM, M, etc.)Estimated from deposit cadence
Deductions breakdownFederal/state taxes, benefits, 401kNot available
W-2 formsAvailable when employer provides themNot available (w2s is always null)
Employment datesFrom payroll recordsNot available
Bank account detailsNot included under employmentsIncluded in the income insights report
Self-employment incomeNot capturedCaptured from deposit patterns
Gig / on-demand incomeNot capturedCaptured from deposit patterns
Government benefitsRequires SSA connectionDetected from deposit patterns

​
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

ScenarioRecommended approach
W-2 employee at a large employerPayroll VOIE — higher data quality and exact figures
Self-employed or freelanceBank income — payroll VOIE has no coverage
Gig worker (Uber, DoorDash, etc.)Bank income — deposits appear in bank transactions
Government benefit recipientBank income or direct SSA connection
Multiple income streamsBoth — payroll VOIE for the primary job, bank income for supplemental sources
Employer not covered by payroll providersBank income as fallback
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