Skip to main content
Verify income and employment by connecting directly to the applicant’s payroll provider. This delivers the highest data quality — verified pay history, employer details, and current employment status — for lending decisions.
Integration pattern: Bridge Widget | Products: VOIE | Demo: PayrollIncome

​
Get started

1

Run the demo

Clone and run the PayrollIncome demo to see the full payroll 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 > Payroll 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 employer — Your server calls GET /v1/company-mappings-search/ to find the applicant’s employer by name. The response returns a company_mapping_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: ["payroll"], and company_mapping_id to deeplink Bridge to the employer.
  4. Initialize Bridge — Your frontend opens Truv Bridge with the bridge_token. The applicant connects their payroll 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 VOIE report — Fetch the report with POST /v1/users//reports/. The report contains verified income and employment data from the payroll provider.
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/PayrollIncome.jsxBridge SDK
Webhook verificationserver/webhooks.jsWebhook events
Report retrievalserver/routes/user-reports.jsIncome reports

​
Consumer Credit-specific configuration

​
Bridge token for payroll income

Set data_sources to ["payroll"] to restrict Bridge to payroll connections only: 
{
  "product_type": "income",
  "data_sources": ["payroll"],
  "company_mapping_id": "COMPANY_MAPPING_ID"
}
Pass company_mapping_id from the company search to deeplink Bridge directly to the employer’s payroll provider. Without it, Bridge shows a generic employer search screen.
Payroll income uses company_mapping_id (not provider_id). The provider_id field is for financial institutions like banks. Passing the wrong identifier type causes Bridge to show a generic search screen.

​
VOIE report

Payroll income verification returns a standard VOIE report containing:
  • Current and historical income (base pay, overtime, bonuses, commissions)
  • Employment details (employer name, hire date, status)
  • Pay frequency and YTD earnings
The income product type includes employment data automatically. You do not need to request employment separately.

​
Next steps

Smart Routing

Automatically recommend payroll, bank, or documents based on employer coverage

Bank Income

Fall back to bank transactions when payroll coverage is low

Bridge Widget Guide

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

Deeplinking

Skip the employer search when you already know the company