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.

When a user authenticates through Truv Bridge, the system creates a Link, a persistent connection to their payroll provider or bank. Each Link has a unique access_token that enables all subsequent data retrieval and modifications. Tasks are the individual actions performed through Links (e.g., fetching income data, switching direct deposits). Each task progresses through a defined status lifecycle.

​
Task status flow

The following diagram illustrates the flow. Tasks progress sequentially through these statuses: 
new → login → mfa → parse → full_parse → done
Not all tasks go through every status. For example, a task may skip mfa if the provider doesn’t require multi-factor authentication, or include switch_deposit for DDS tasks.

​
Status definitions

StatusDescription
newTask initiated, queued for processing
loginAttempting to log into the payroll provider or bank
mfaCompleting multi-factor authentication
parseCollecting identity, employment, and paystub data
full_parseInitial parse complete; downloading and parsing paystubs, W-2s, and additional income sources
switch_depositProcessing direct deposit allocation changes (DDS tasks only)
doneTask completed successfully

​
Error states

Tasks may enter an error state at any point in the lifecycle:
Error statusDescriptionRecommended action
login_errorAuthentication failed: incorrect credentialsPrompt the user to re-authenticate via Bridge Update Mode
mfa_errorMulti-factor authentication was not completedPrompt the user to retry, or offer document upload as fallback
config_errorDocument processing or configuration failureFetch the task record for the specific error_message. See Fraud & Manual Review.
account_lockedThe payroll or bank account is lockedAsk the user to unlock their account directly with the provider before retrying
unable_to_resetFailed to reset credentials at the providerRoute the user to manual verification
no_dataProvider connected successfully but returned no dataOffer document upload as fallback. Do not treat as verified $0 income.
unavailableProvider service is temporarily inaccessibleRetry later or route to document upload. Not user-fixable.
not_supportedProvider or HRIS system is not supportedInform the user and offer document upload
errorGeneric connection failureLog the task_id and contact support if the error persists
Subscribe to task-status-updated webhooks to receive error states in real time. See Task Webhook Events for the full list of task events.

​
Data processing

See Data Processing for stage timing, median durations, data availability at each stage, and typical processing times.

​
Relationship to Orders

Orders are the top-level containers for verification requests. When a user completes an Order:
  1. The user authenticates through Bridge, creating a Link
  2. A Task is created on that Link to retrieve the requested data
  3. The Task progresses through the status lifecycle
  4. On completion, data is available via the API and the order status updates
A single Order can have multiple connections (e.g., a borrower connecting two employers), each with their own Link and Tasks.

​
Monitor tasks

​
Dashboard

View task details in the Dashboard under Activity > Tasks. Filter by status, date, and provider.

​
API

Retrieve task status programmatically: 
curl -X GET "https://prod.truv.com/v1/tasks/?query={link_id}" \
  -H "X-Access-Client-Id: your_client_id" \
  -H "X-Access-Secret: your_secret"

​
Webhooks

Subscribe to task events for real-time monitoring:
  • task-status-updated with status: done: task finished successfully
  • task-status-updated with an error status: task encountered an error