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. For clients who apply by phone or in person, see Offline & Contact Center.
Integration pattern: Hosted Orders | Products: VOIE, VOE, VOA | Demo: Case Worker Portal

​
Get started

1

Run the demo

Clone and run the Case Worker Portal demo to see the full caseworker-to-client flow working locally.
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.

​
Public Sector-specific configuration

​
Identify the applicant and the case

Two identifiers do two different jobs. external_user_id identifies the person; order_number carries your agency’s case.
Never send one external_user_id for two people. It resolves to a single applicant profile: the first person’s name is kept and the SSN is overwritten by the most recent order, leaving one person’s name attached to another’s SSN.If you omit external_user_id, Truv falls back to order_number as the user identifier — so a shared case ID with no external_user_id merges the whole household into one profile. Always send it explicitly. See Use external_user_id for user continuity.
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:
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. Give each member their own external_user_id, and put the shared case ID in order_number. Truv sends each member their own verification link. Retrieve every order on a case with GET /v1/orders/?search={order_number}.
Bulk loading a household needs a different approach. POST /v1/orders/batch/ requires order_number to be unique within the environment, so members sharing one case ID do not all load — the second is skipped, reported as existing, and handed back the first member’s verification link. Because created_count counts existing alongside created, the job still reports every order as usable. Give each member a distinct order_number in a batch, or create household orders individually.

​
Follow-up tasks

When a client doesn’t complete verification after receiving a link, configure follow-up notifications to send automatic reminders. 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

Offline & Contact Center

Verify clients who apply by phone or in person

Renewals

Re-verify clients at recertification

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