New User - Truv

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 information
Truv sends a notification (email, SMS, or both) with a link to the hosted verification page
User connects accounts on Truv’s hosted page (payroll, banks)
Receive data via webhook notifications
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.

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
`products`	array	Yes	Products to request: `income`, `employment`, `assets`
`first_name`	string	Yes	User’s first name
`last_name`	string	Yes	User’s last name
`email`	string	Yes*	User’s email for notifications
`phone`	string	No	User’s phone for SMS notifications
`ssn`	string	No	SSN for identity matching (4 or 9 digits)
`external_user_id`	string	No	Your internal user/application identifier
`template_id`	string	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
`goodlogin`	`goodpassword`	Full-time current employment
`hourly.part-time`	`goodpassword`	Hourly part-time worker
`multiple.employments`	`goodpassword`	Multiple 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.

​How it works

​Implement

​Step 1: Create an order [Server-side]

​Step 2: Test in sandbox

​Step 3: Monitor webhooks [Server-side]

​Step 4: Retrieve data [Server-side]

​Order statuses

​No-code alternative

​Set expiration and reminders

​Next steps

Add Employer

Data Refresh

Deeplinking

Self-Certification

Verifier Portal Demo

How it works

Implement

Step 1: Create an order [Server-side]

Step 2: Test in sandbox

Step 3: Monitor webhooks [Server-side]

Step 4: Retrieve data [Server-side]

Order statuses

No-code alternative

Set expiration and reminders

Next steps