Skip to main content
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.
For the simplest integration, create an Order and let Truv handle everything: User creation, Bridge Token generation, and invite delivery. Use the lower-level User and Bridge Token APIs only when you need full control over the frontend experience.

​
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.
AttributeTypeDescription
idstringUnique identifier for the Order
statusstringCurrent order status
product_typestringVerification product type
share_urlstringLanding page URL for the user
bridge_tokenstringToken to initialize Truv Bridge

​
Users

A User represents a person connecting their accounts through Truv Bridge. Each User can have multiple Links across different providers.
AttributeTypeDescription
idstringUnique identifier for the User
external_user_idstringYour internal identifier
first_namestringFirst name (required)
last_namestringLast name (required)
emailstringUser email
phonestringUser phone number
ssnstringSocial Security Number
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.
AttributeTypeDescription
idstringUnique identifier for the Link
access_tokenstringToken for retrieving data from this connection
provider_idstringThe data provider the user connected to
statusstringCurrent connection status
tracking_infostringOptional tracking information

​
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.
data_sourceDescriptionRetrieval endpoint
payrollPayroll provider parsingGET /v1/links/{link_id}/income/report/ for income data, GET /v1/links/{link_id}/employment/report/ for employment-only data
docsUser-uploaded documentsPre-signed URLs returned in the document upload response. Access the file field on each statement or W-2 object.
financial_accountsBank account data (VOA)POST /v1/users/{user_id}/assets/reports/ to generate an asset report, or use the income insights endpoints for transaction-based income analysis
insuranceInsurance provider dataRetrieved through the insurance suborder on the Order object
taxTax documentsRetrieved through the tax document endpoints on the Link
scoring_attributesTransaction scoring attributesRetrieved through the scoring attributes report endpoints
For payroll sources, the income product automatically includes employment data. You do not need to make a separate employment request if you already requested income.

​
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.
FieldObjectFormatMax value
gross_payStatements, Annual income summary, W2sDecimal string, 2 decimal places9999999999.99
net_payStatements, Annual income summaryDecimal string, 2 decimal places9999999999.99
hoursStatementsDecimal string, 2 decimal places9999999999.99
incomeEmploymentsDecimal string, 2 decimal places9999999999.99
pay_rateEmploymentsDecimal string, 2 decimal places9999999999.99
bonusStatements, Annual income summaryDecimal string, 2 decimal places9999999999.99
commissionStatements, Annual income summaryDecimal string, 2 decimal places9999999999.99
overtimeStatements, Annual income summaryDecimal string, 2 decimal places9999999999.99
regularStatements, Annual income summaryDecimal string, 2 decimal places9999999999.99
other_payStatements, Annual income summaryDecimal string, 2 decimal places9999999999.99
deposit_valueBank accountsDecimal string, 2 decimal places9999999999.99
wagesW2sDecimal string, 2 decimal places9999999999.99
All numeric values are returned as strings (e.g., "70000.00"), not as JSON numbers. Parse them as decimals in your application to avoid floating-point precision issues.