Skip to main content
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 StatusDescription
login_errorAuthentication failed: incorrect credentials
mfa_errorMulti-factor authentication was not completed
config_errorConfiguration issue requiring user or developer action
account_lockedThe payroll or bank account is locked
unable_to_resetFailed to reset credentials at the provider
no_dataProvider connected successfully but returned no data
unavailableProvider service is temporarily inaccessible
errorGeneric connection failure
not_supportedProvider or HRIS system is not supported
Use webhooks to get real-time notifications when tasks complete or encounter errors. 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