Skip to main content

Documentation Index

Fetch the complete documentation index at: https://truv.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 methodBest for
APIProgrammatic workflows, automated pipelines
DashboardManual order creation, one-off verifications
CSV bulk uploadHigh-volume batch processing

​
How it works

  1. Create an order via API with the user’s contact information
  2. Truv sends a notification (email, SMS, or both) with a link to the hosted verification page
  3. User connects accounts on Truv’s hosted page (payroll, banks)
  4. Receive data via webhook notifications
  5. Retrieve 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. 
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"
}'
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.
FieldTypeRequiredDescription
productsarrayYesProducts to request: income, employment, assets
first_namestringYesUser’s first name
last_namestringYesUser’s last name
emailstringYes*User’s email for notifications
phonestringNoUser’s phone for SMS notifications
ssnstringNoSSN for identity matching (4 or 9 digits)
external_user_idstringNoYour internal user/application identifier
template_idstringNoCustomization 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.
UsernamePasswordDescription
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

StatusDescription
PendingOrder created, system processing
SentEmail or SMS sent to the user
CompletedUser connected their account
ErrorNotification delivery failed
CanceledOrder manually canceled
ExpiredOrder exceeded its expiration window
SkippedUser opened the link but did not complete
No DataUser 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.