Task Lifecycle

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

Every task authenticates through the Link first, then follows one of two paths depending on its type. A task may skip mfa when the provider doesn’t require multi-factor authentication.

Standard tasks

A standard task collects data from the connected account:

new → login → mfa → parse → full_parse → done

DDS tasks

A Direct Deposit Switch task replaces parse and full_parse with switch_deposit:

new → login → mfa → switch_deposit → done

Status definitions

Status	Description
new	Task initiated, queued for processing
login	Attempting to log into the payroll provider or bank
mfa	Completing multi-factor authentication
parse	Collecting identity, employment, and paystub data
full_parse	Initial parse complete; downloading and parsing paystubs, W-2s, and additional income sources
switch_deposit	Processing direct deposit allocation changes (DDS tasks only)
done	Task completed successfully

Error states

Tasks may enter an error state at any point in the lifecycle:

Error status	Description	Recommended action
login_error	Authentication failed: incorrect credentials	Prompt the user to re-authenticate via Bridge Update Mode
mfa_error	Multi-factor authentication was not completed	Prompt the user to retry, or offer document upload as fallback
config_error	Provider integration or configuration issue. Also raised when uploaded documents fail fraud/tampering checks.	Fetch the task record for the specific `error_message`. For document tampering, see Fraud & Manual Review.
account_locked	The payroll or bank account is locked	Ask the user to unlock their account directly with the provider before retrying
unable_to_reset	Failed to reset credentials at the provider	Route the user to manual verification
no_data	Provider connected successfully but returned no data	Offer document upload as fallback. Do not treat as verified $0 income.
unavailable	Provider service is temporarily inaccessible	Retry later or route to document upload. Not user-fixable.
not_supported	Provider or HRIS system is not supported	Inform the user and offer document upload
error	Generic connection failure	Log 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:

The user authenticates through Bridge, creating a Link
A Task is created on that Link to retrieve the requested data
The Task progresses through the status lifecycle
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

​Task status flow

​Standard tasks

​DDS tasks

​Status definitions

​Error states

​Data processing

​Relationship to Orders

​Monitor tasks

​Dashboard

​API

​Webhooks

Task status flow

Standard tasks

DDS tasks

Status definitions

Error states

Data processing

Relationship to Orders

Monitor tasks

Dashboard

API

Webhooks