Hosted orders let Truv handle user outreach. Create an order with the user’s contact information, and Truv sends an email or SMS with a link to complete verification. No app or widget integration required.
At least one of email or phone is required. Truv needs a way to contact the user. Providing both maximizes success rates.
Creation method Best for API Programmatic workflows, automated pipelines Dashboard Manual order creation, one-off verifications CSV bulk upload High-volume batch processing
How it works
Create an order via API with the user’s contact informationTruv sends a notification (email, SMS, or both) with a link to the hosted verification pageUser connects accounts on Truv’s hosted page (payroll, banks)Receive data via webhook notificationsRetrieve results using the order ID
Implement Step 1: Create an order [Server-side] Create an Order with the user’s name and contact information. Truv sends the verification link automatically.
Income
Assets
Income & Assets
curl --request POST \ --url https://prod.truv.com/v1/orders/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Content-Type: application/json' \ --data '{ "products": ["income"], "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "4155554193", "ssn": "222233333" }'
curl --request POST \ --url https://prod.truv.com/v1/orders/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Content-Type: application/json' \ --data '{ "products": ["assets"], "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "4155554193" }'
curl --request POST \ --url https://prod.truv.com/v1/orders/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Content-Type: application/json' \ --data '{ "products": ["income", "assets"], "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "4155554193", "ssn": "222233333" }'
The response includes a short_share_url, the hosted verification link to send to the user.
{ "id" : "39aa1486ccca4bc19cda071ffc1ba392" , "products" : [ "income" ], "first_name" : "John" , "last_name" : "Doe" , "user_id" : "99dd17074ac94aa9ace2621d657c7610" , "bridge_token" : "e4100fccdae94691b4414c7306220c06" , // ... additional fields "short_share_url" : "https://truv.link/abc123" , // ... status, timestamps, employers }
Specify only the products your use case requires.
Field Type Required Description productsarray Yes Products to request: income, employment, assets first_namestring Yes User’s first name last_namestring Yes User’s last name emailstring Yes* User’s email for notifications phonestring No User’s phone for SMS notifications ssnstring No SSN for identity matching (4 or 9 digits) external_user_idstring No Your internal user/application identifier template_idstring No Customization template to apply
If you already know the user’s employer, use deeplinking to skip the search screen.
Step 2: Test in sandbox Test your implementation with sandbox credentials.
Username Password Description goodlogingoodpasswordFull-time current employment hourly.part-timegoodpasswordHourly part-time worker multiple.employmentsgoodpasswordMultiple employers
See Test Credentials for all scenarios.
Step 3: Monitor webhooks [Server-side] Webhooks notify you when task and order statuses change. Use user_id to match events to a specific order.Task-level webhook, fires as each connection progresses.
{ "webhook_id" : "17a80437ce23411dbfd656694d19a8c6" , "event_type" : "task-status-updated" , "event_created_at" : "2024-07-11T21:43:08.073930Z" , "product" : "income" , "link_id" : "d8a8945ee2b049b193110cfba643f5df" , "user_id" : "adbe707dddee4334bffaeb5866272740" , "data_source" : "payroll" , "task_id" : "871fef2e79ea444ea2019c8845305d31" , "tracking_info" : null , "status" : "done" , "template_id" : null , "updated_at" : "2024-07-11T21:43:08.075540+00:00" }
Order-level webhook, fires when the user finishes the order.
{ "webhook_id" : "0aac461e7b774a38a72fd9c7c0eef8ee" , "event_type" : "order-status-updated" , "event_created_at" : "2024-07-11T21:40:48.424610Z" , "product" : "income" , "link_id" : "d8a8945ee2b049b193110cfba643f5df" , "user_id" : "adbe707dddee4334bffaeb5866272740" , "data_source" : "payroll" , "order_id" : "ddd192646b3c48be96651a0ff25cef85" , "order_number" : "4138538" , "employer_id" : "d7166cffbfef4bd6a9e830cf5508e615" , "status" : "completed" , "template_id" : null , "updated_at" : "2024-07-11T21:40:48.424655+00:00" }
See Task lifecycle for all status transitions.
Step 4: Retrieve data [Server-side] Fetch order details using the order_id. The response includes employer data, employment history, income statements, and report IDs.
curl --request GET \ --url https://prod.truv.com/v1/orders/39aa1486ccca4bc19cda071ffc1ba392/ \ --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \ --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \ --header 'Accept: application/json'
See Order object for the full response schema.
Order statuses Status Description Pending Order created, system processing Sent Email or SMS sent to the user Completed User connected their account Error Notification delivery failed Canceled Order manually canceled Expired Order exceeded its expiration window Skipped User opened the link but did not complete No Data User connected but the provider returned no data
No-code alternative Create orders through the Dashboard UI without any API integration: single orders or bulk via CSV. See Manual Orders .
Set expiration and reminders The default expiration window is 72 hours , configurable from 1 day to 12 weeks. Expiration periods do not count weekends. Configure expiration and automatic reminders in the Dashboard under Customization , or set expired_at when creating orders via API.
Next steps
Add Employer Add additional employers to an existing order
Data Refresh Refresh data from existing connections
Deeplinking Pre-fill employer info to skip search
Self-Certification Let users review and confirm retrieved data
Verifier Portal Demo Send verification links via email/SMS. The applicant completes Bridge on their own device.
