Skip to main content
Route each applicant to the fastest verification path — payroll, bank transactions, or document upload — based on their employer’s payroll coverage. The system checks coverage via company search, recommends a method, and lets the applicant confirm or override.
Integration pattern: Bridge Widget | Products: VOIE, Income Insights | Demo: SmartRouting

​
Get started

1

Run the demo

Clone and run the SmartRouting demo to see the full smart routing 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 > Smart Routing, 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 employer — Your server calls GET /v1/company-mappings-search/ to find the applicant’s employer. The success_rate field in the response determines the recommendation: high suggests payroll, low/medium suggests bank, and no results suggests documents.
  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 the selected data_sources array (["payroll"], ["financial_accounts"], or ["docs"]). Pass company_mapping_id for payroll to deeplink Bridge to the employer.
  4. Initialize Bridge — Your frontend opens Truv Bridge with the bridge_token. The applicant connects their provider.
  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 report — For payroll or document methods, fetch the VOIE report with POST /v1/users/{user_id}/reports/. For bank income, fetch the income insights report with POST /v1/users/{user_id}/income_insights/reports/.
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
Employer searchsrc/components/CompanySearch.jsxCompany Search
User creationserver/routes/bridge.jsPOST /v1/users/
Bridge tokenserver/routes/bridge.jsPOST /v1/users//tokens/
Bridge initializationsrc/demos/SmartRouting.jsxBridge SDK
Webhook verificationserver/webhooks.jsWebhook events
Report retrievalserver/routes/user-reports.jsIncome reports

​
Consumer Credit-specific configuration

​
Routing logic

The success_rate field from company search drives the recommendation:
success_rate valueRecommended methoddata_sources
highPayroll["payroll"]
low / mediumBank transactions["financial_accounts"]
No resultsDocument upload["docs"]
The applicant can always override the recommendation and pick any method.

​
Data sources

Control which verification methods Bridge shows by setting the data_sources array when creating the bridge token: 
{
  "product_type": "income",
  "data_sources": ["payroll"],
  "company_mapping_id": "COMPANY_MAPPING_ID"
}
For payroll, pass company_mapping_id to deeplink Bridge to the employer. For bank income, pass provider_id to deeplink to the financial institution. Document upload requires no additional identifier.

​
Report types

The report endpoint depends on the method the applicant chose:
MethodReport endpointReport type
PayrollPOST /v1/users/{user_id}/reports/VOIE
Bank transactionsPOST /v1/users/{user_id}/income_insights/reports/Income Insights
DocumentsPOST /v1/users/{user_id}/reports/VOIE

​
Next steps

Bank Income

Verify income from bank transactions when payroll coverage is low

Payroll Income

Connect directly to payroll for the highest data quality

Bridge Widget Guide

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

Deeplinking

Skip the provider search screen when you already know the employer or bank