> ## 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.
# Bank Income
> Verify applicant income from bank transactions using income insights
Verify income by connecting to the applicant's bank account and analyzing transaction history. Truv generates an [income insights report](/api-reference/income-insights/income-insights-report-create) from deposit patterns, giving you income data even when payroll connections are unavailable.
**Integration pattern:** [Bridge Widget](/developers/integration/bridge-widget/overview) | **Products:** Income Insights | **Demo:** [Bank Income](/developers/demos/consumer-credit/bank-income)
***
## Get started
Clone and run the [Bank Income demo](/developers/demos/consumer-credit/bank-income) to see the full bank income verification flow working locally.
```bash theme={null}
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](/developers/quickstarts-overview#demo-apps) for ngrok and environment configuration.
The demo follows this sequence:
1. **Search for financial institution** -- Your server calls [GET /v1/providers/](/api-reference/data-providers/providers-list) 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/](/api-reference/users/users_create) to create a Truv user.
3. **Create a bridge token** -- Your server calls [POST /v1/users/{id}/tokens/](/api-reference/bridge-token/users_tokens) with `product_type: "income"`, `data_sources: ["financial_accounts"]`, and optionally `provider_id` to [deeplink](/developers/integration/bridge-widget/deeplinking) Bridge to the bank.
4. **Initialize Bridge** -- Your frontend opens [Truv Bridge](/developers/sdks/overview) with the `bridge_token`. The applicant connects their bank account.
5. **Receive webhooks** -- Truv sends a `task-status-updated` [webhook](/api-reference/webhooks) 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/{user_id}/income\_insights/reports/](/api-reference/income-insights/income-insights-report-create). The report contains income derived from bank transaction analysis.
Each step maps to a specific file in the demo. Use these as reference when building your integration.
| Step | Demo file | API reference |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Institution search | [`src/components/CompanySearch.jsx`](https://github.com/truvhq/demo-apps/blob/main/src/components/CompanySearch.jsx) | [Providers List](/api-reference/data-providers/providers-list) |
| User creation | [`server/routes/bridge.js`](https://github.com/truvhq/demo-apps/blob/main/server/routes/bridge.js) | [POST /v1/users/](/api-reference/users/users_create) |
| Bridge token | [`server/routes/bridge.js`](https://github.com/truvhq/demo-apps/blob/main/server/routes/bridge.js) | [POST /v1/users/{id}/tokens/](/api-reference/bridge-token/users_tokens) |
| Bridge initialization | [`src/demos/BankIncome.jsx`](https://github.com/truvhq/demo-apps/blob/main/src/demos/BankIncome.jsx) | [Bridge SDK](/developers/sdks/overview) |
| Webhook verification | [`server/webhooks.js`](https://github.com/truvhq/demo-apps/blob/main/server/webhooks.js) | [Webhooks](/api-reference/webhooks) |
| Report retrieval | [`server/routes/user-reports.js`](https://github.com/truvhq/demo-apps/blob/main/server/routes/user-reports.js) | [Income Insights Report](/api-reference/income-insights/income-insights-report-create) |
***
## Consumer Credit-specific configuration
### Bridge token for bank income
Set `data_sources` to `["financial_accounts"]` to restrict Bridge to bank connections only:
```json theme={null}
{
"product_type": "income",
"data_sources": ["financial_accounts"],
"provider_id": "PROVIDER_ID"
}
```
Pass `provider_id` from the [providers search](/api-reference/data-providers/providers-list) 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](/api-reference/income-insights/income-insights-report-create) 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](/credit/integration/payroll-income) verification.
### Data comparison
| Data point | Payroll VOIE | Bank income |
| ---------------------- | ------------------------------------- | ------------------------------------------------------ |
| Income amount | Exact gross/net from paystubs | Estimated from deposit patterns |
| Employer name | From payroll provider | Not available (inferred from transaction descriptions) |
| Pay frequency | Exact (`BW`, `SM`, `M`, etc.) | Estimated from deposit cadence |
| Deductions breakdown | Federal/state taxes, benefits, 401k | Not available |
| W-2 forms | Available when employer provides them | Not available (`w2s` is always null) |
| Employment dates | From payroll records | Not available |
| Bank account details | Not included under employments | Included in the income insights report |
| Self-employment income | Not captured | Captured from deposit patterns |
| Gig / on-demand income | Not captured | Captured from deposit patterns |
| Government benefits | Requires SSA connection | Detected 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
| Scenario | Recommended approach |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| W-2 employee at a large employer | Payroll VOIE -- higher data quality and exact figures |
| Self-employed or freelance | Bank income -- payroll VOIE has no coverage |
| Gig worker (Uber, DoorDash, etc.) | Bank income -- deposits appear in bank transactions |
| Government benefit recipient | Bank income or direct SSA connection |
| Multiple income streams | Both -- payroll VOIE for the primary job, bank income for supplemental sources |
| Employer not covered by payroll providers | Bank income as fallback |
For the most complete income picture, include both `income` and `assets` products in your [order](/api-reference/orders/orders_create). 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
Automatically recommend the best method based on employer coverage
Verify income directly from payroll for higher data quality
Full implementation guide for user creation, bridge tokens, and Bridge initialization
Full API reference for income insights reports