Data Structure

The Truv API is built around four core objects: Orders, Users, Links, and Tasks. Understanding how they connect is essential before integrating.

​

Object relationships

Every verification follows the same path through these objects:

1. Order → User. You create an Order with the applicant’s details. Truv automatically creates a User, generates a Bridge Token, and builds a landing page with a unique share_url. You can also create Users directly via the API if you manage your own frontend flow.
2. User → Bridge Token. A Bridge Token is a short-lived credential scoped to a single User. It controls which products the User can access, supports deeplinking to pre-select a provider, and sets the customization template. Pass it to your frontend to initialize Truv Bridge.
3. Bridge Token → Link. When the User authenticates with a data provider (payroll system, bank, or tax portal) through Truv Bridge, the system creates a Link, a persistent connection to that provider. The Link has an access_token for all subsequent data operations. If the same User reconnects with the same credentials to the same provider, Truv returns the existing Link rather than creating a duplicate.
4. Link → Task. Each data retrieval or action through a Link is a Task: fetching income data, switching a direct deposit, or refreshing stale data. A single Link can have multiple Tasks over its lifetime.
5. Task → Data. When a Task completes successfully, the verification data becomes available through the Link’s data endpoints. Listen for task-status-updated webhooks to know when data is ready.

---

​

Orders

An Order is the starting point for every verification. Creating an Order automatically creates a User, generates a Bridge Token, and produces a landing page for the user to connect their account.

​

Users

A User represents a person connecting their accounts through Truv Bridge. Each User can have multiple Links across different providers, and each Link carries its own access_token, so a User with multiple connections has multiple access_tokens.

​

Links

A Link is a persistent connection to a data provider for a specific User. Reusing the same credentials for the same provider returns the same Link.

​

Tasks

A Task is an individual action performed through a Link: fetching verification data, switching direct deposits, or refreshing a connection. Each Task progresses through a defined status flow from new to done or error. See Task Lifecycle for the full status diagram, processing times, and error handling.

​

Data retrieval by source

After a Task completes, the endpoint you use to retrieve data depends on the data_source value on the employer or financial account suborder.

---

​

Field constraints

Numeric fields across Truv’s API use a consistent precision format. All monetary and quantity fields are stored as DecimalField(max_digits=12, decimal_places=2), meaning up to 10 digits before the decimal point and exactly 2 digits after.