Skip to main content
Create verification orders from your caseworker system and send clients a link to complete verification on their own device. Truv delivers the link via email or SMS, tracks completion, and returns verified data through webhooks. This pattern also supports contact center agents and in-person office visits.
Integration pattern: Hosted Orders | Products: VOIE, VOE, VOA | Demo: EmployeePortal

​
Get started

1

Run the demo

Clone and run the EmployeePortal demo to see the full caseworker-to-client 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 > Case Worker Portal, add a test client with an email address, and send a verification request. The demo tracks order status and displays reports when the client completes Bridge.See full setup instructions for ngrok and environment configuration.
2

Understand the API flow

The demo follows this sequence:
  1. Create an order — Your server sends client PII (name, email, phone) and selected products to POST /v1/orders/. The response includes order_id, share_url, and user_id.
  2. Deliver the link — Truv sends the share_url to the client via email and/or SMS automatically. For agency-managed notifications, suppress Truv emails and send the share_url through your own messaging system.
  3. Client completes Bridge — The client opens the link, searches for their employer, and connects their payroll account on their own device.
  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
Order creationserver/routes/orders.jsPOST /v1/orders/
Caseworker dashboardsrc/demos/EmployeePortal.jsxHosted Orders
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 identifier. Group all household member orders under the same case ID for unified tracking. 
{
  "products": ["income"],
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "4155554193",
  "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.

​
Notification delivery

Choose how the client receives the verification link:
MethodConfigurationBest for
Truv-managedInclude email and/or phone in the orderAutomatic delivery with configurable reminders
Agency-managedSet suppress_user_notifications: true, use share_url from the responseAll communications must come from state systems
DashboardCreate orders through the Truv Dashboard or CSV bulk uploadNo code required
For agency-managed notifications, use the short_share_url from the order response for SMS and the full share_url for email.

​
Household members

Create a separate order for each household member. Use the same external_user_id to group all orders under one case. Truv sends each member their own verification link.

​
Renewals and data refresh

At recertification time, use the Order Refresh API to pull updated income and employment data from an existing order’s connections. When the session is still active, the client does not need to take any action — Truv reuses the original account link and returns fresh data.

​
Refresh workflow

1

Identify the original order

When a case is due for recertification, look up the original Truv order ID associated with the client’s case record.
2

Create a refresh order

Send a POST request to the original order’s endpoint. Specify which product to refresh and, optionally, which employers to include. The refresh creates a new order with its own ID. Omit the employers array to refresh all connections from the original order. See the Data Refresh guide for the full request example.
3

Receive updated data

Listen for the task-status-updated webhook with status: "done" on the new order. Retrieve the refreshed report and pre-fill the caseworker review screen with updated income, employment status, and pay history.

​
When refresh fails

Refreshes fail when the client’s session has expired or their credentials have changed. The webhook returns login_error or mfa_error.
ScenarioCauseWhat to do
Session expiredPayroll provider session timed out or requires MFACreate a new order and send a fresh verification link through your renewal process
Credentials changedClient changed their payroll login passwordCreate a new order — the client re-authenticates through Bridge
Provider unavailablePayroll provider is temporarily downRetry the refresh after some time
OAuth-based payroll connections typically expire after ~180 days. For programs with annual recertification cycles, plan for re-authentication on most renewals. For programs with periodic eligibility reviews, refresh success rates are significantly higher.

​
Refresh limits

  • 3 refreshes per connection per 24-hour period
  • Each refresh is billed as a separate verification

​
Bulk renewals

For agencies processing many renewals at once, automate refresh order creation by iterating over cases due for recertification. Check each refresh result: if it succeeds, pre-fill the caseworker screen automatically. If it fails, queue the case for a new verification link. See Data Refresh for the full implementation guide, including Bridge Update Mode for re-authentication.

​
Contact center

Contact center agents use the same caseworker portal flow — create an order during the phone call and send the verification link while the client is on the line.
  1. Agent creates order — During the call, the agent enters client details and creates an order through the Dashboard or API.
  2. Send link via SMS — Use the short_share_url from the order response to send an SMS to the client’s phone during the call.
  3. Client completes verification — The client opens the link on their phone and connects their payroll or bank accounts while still on the call (or shortly after).
  4. Agent monitors status — The Dashboard or your caseworker system shows real-time order status. The agent can confirm completion before ending the call.
For contact center deployments, set first_notification_delay_hours to a low value (e.g., 1) so clients who don’t complete during the call receive a reminder quickly.

​
In-person QR code

For office visits, generate a QR code from the order’s share_url so clients can verify on their own phone at the office.
  1. Caseworker creates order — Create an order via the Dashboard or API with the client’s case information.
  2. Display QR code — Generate a QR code from the share_url and display it on the caseworker’s screen or print it.
  3. Client scans and verifies — The client scans the QR code with their phone, opens Bridge, and connects their payroll or bank accounts.
  4. Results flow back — Truv sends verified data through webhooks. The caseworker sees results in the Dashboard or caseworker system.
QR codes work with any QR code generator — encode the share_url value. The same link works whether scanned from a screen or printed handout.

​
Follow-up tasks

When a client doesn’t complete verification after receiving a link, configure follow-up notifications to send automatic reminders.
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 caseworker-initiated workflows, the caseworker can also manually resend the link from the Dashboard or trigger a new notification through the API.

​
Next steps

Customer Portal

Embed verification in the client-facing portal

Document Processing

Extract income data from uploaded documents

Hosted Orders Guide

Full implementation guide for hosted order creation and notification delivery

Sandbox Testing

Test with government-specific scenarios