Skip to main content
Truv Bridge embedded in a government benefits portal Verify client income, employment, and assets in real-time by embedding Truv Bridge directly in your benefits portal. The client searches for their employer, connects their accounts, and completes verification without leaving your system.
Integration pattern: Embedded Orders | Products: VOIE, VOE, VOA | Demo: CustomerPortal

​
Get started

1

Run the demo

Clone and run the CustomerPortal demo to see the full client self-service flow working locally.
git clone https://github.com/truvhq/demo-apps.git
cd demo-apps
npm install && npm start
Open http://localhost:5173, select Public Sector > Customer Portal, choose a product (income, employment, or assets), 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 client’s employer by name. For asset verification, search financial institutions with GET /v1/providers/.
  2. Create an order — Your server sends client PII, case ID, and selected products to POST /v1/orders/. The response includes a bridge_token and user_id.
  3. Initialize Bridge — Your frontend opens Truv Bridge with the bridge_token. Set isOrder: true and optionally pass companyMappingId to deeplink directly to the employer.
  4. Receive webhooks — Truv sends an order-status-updated webhook when verification completes. Verify the signature using the X-Webhook-Sign header with HMAC-SHA256.
  5. Retrieve reports — Fetch the VOIE report with POST /v1/users/{user_id}/reports/ or the assets report with POST /v1/users/{user_id}/assets/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
Order creationserver/routes/orders.jsPOST /v1/orders/
Bridge initializationsrc/demos/CustomerPortal.jsxBridge SDK
Webhook verificationserver/webhooks.jsWebhook events
Report retrievalserver/routes/user-reports.jsIncome reports

​
Public Sector-specific configuration

​
Case ID tracking

Use external_user_id to link orders to your agency’s case or application identifier. This enables data continuity across verifications, renewals, and household members. 
{
  "products": ["income", "assets"],
  "first_name": "John",
  "last_name": "Doe",
  "ssn": "222233333",
  "external_user_id": "case-12345",
  "template_id": "YOUR_TEMPLATE_ID",
  "locale": "es"
}
Pass template_id to apply your agency’s customized template (branding, messaging, landing page). Pass locale to set the client’s language — see threshold languages for all supported values.

​
Products

Request the products your eligibility determination requires:
ProductUse caseReport
incomeSNAP, TANF, Medicaid, housing assistanceVOIE (includes employment data)
employmentEmployment status confirmation, compliance checksVOE
assetsMeans testing, housing assistanceVOA + Income Insights
The income product includes employment verification automatically. Do not pass both income and employment.

​
Household members

Create separate orders for each household member who needs to verify income. Use the same external_user_id (case ID) to group orders under one case.
ApproachHow it worksBest for
Portal tasksCreate a to-do item in the portal for each household memberAgencies with portal login for all members
Email / SMSCreate an order with contact info and let Truv send the linkAgencies that collect contact consent

​
Content Security Policy

If your portal uses a Content Security Policy, allow my.truv.com (frame-src) and cdn.truv.com (script-src) for Bridge to load.
Missing CSP configuration is the most common cause of the widget failing to load. Check your CSP settings first if Bridge doesn’t appear.

​
Renewals and data refresh

When a client’s case is due for recertification, use the Order Refresh API to pull updated data from their existing payroll and bank connections. If the session is still active, the client does not need to do anything — Truv returns fresh data automatically.
ScenarioWhat happensClient action
Session still activeRefresh succeeds. Your system receives updated income and employment data via webhook. Pre-fill the caseworker review screen.None
Session expiredRefresh fails with login_error or mfa_error. The client needs to re-authenticate.Complete verification through a new link
Recommended renewal flow:
  1. Attempt a refresh first. When a case is due for recertification, create a refresh order against the original order. This is a server-side call — no portal interaction needed.
  2. If the refresh succeeds, route the updated data to the caseworker review screen. The client’s portal can show a “Verification complete” status with no action required.
  3. If the refresh fails, display a verification task in the client’s portal. The client logs in, sees the pending task, and completes a new verification through Bridge.
For programs with periodic eligibility reviews, most refreshes succeed because sessions stay active. For annual recertification, expect more re-authentication. Plan your portal UX for both paths.
See Data Refresh for the full implementation guide, including refresh limits (3 per connection per 24 hours) and failure handling.

​
Self-certification

Enable self-certification to let clients review and confirm retrieved income and employment data before submission. After verification, the client sees their data and marks it as representative or flags discrepancies. Self-certification is especially useful for:
  • Clients with multiple income sources or irregular pay
  • Self-employed clients confirming bank transaction data
  • Programs that require client attestation
Retrieve certification results from the certifications endpoint after the order completes. For cases where the client verifies outside your portal (e.g., a caseworker sends a link during an office visit or phone call), you can embed the Truv verification link in your own communications:
FieldUse
share_urlFull URL for email links
short_share_urlShortened URL for SMS messages
To use your own email/SMS system instead of Truv’s, set suppress_user_notifications: true in the order’s notification_settings and deliver the share_url yourself. Order links expire based on your template configuration. To configure link expiry, set the expiration in your template settings or pass it in the order request.

​
Follow-up tasks

When a client starts but doesn’t complete verification, configure follow-up notifications to bring them back. Truv sends email/SMS reminders automatically based on your notification_settings.
SettingDescription
suppress_user_notificationsSet to false (default) to enable Truv-managed reminders
first_notification_delay_hoursHours to wait before the first reminder (default: 0)
For portal-integrated workflows, you can also display incomplete verifications as pending tasks in your portal UI and let the client resume where they left off.

​
Next steps

Caseworker Portal

Send verification links and ingest data into caseworker screens

Deeplinking

Skip the employer search screen for higher completion rates

Sandbox Testing

Test with government-specific scenarios

Embedded Orders Guide

Full implementation guide for order creation, Bridge, callbacks, and data retrieval