Connection Lifecycle

Learn about Truv statuses and processes for retrieving, processing, and writing data.

Overview

Truv works using Tasks on connected accounts to collect user information. Tasks use Link connections with providers to perform actions, such as retrieving and writing data. When connecting to providers, Truv processes user data in stages. Find information for Tasks and data processing below.

Task status lifecycle

When users first connect payroll accounts using Truv Bridge, Truv creates a Link. This connection to payroll providers has a unique ID value, the link ID or access_token.

Truv uses the access_token value with Links to collect reports and initiate data refreshes. Each action when working with Links creates a Task. Truv then initiates the request on the payroll provider before continuing.

Each section below covers Task statuses and definitions.

Task statuses

Truv Tasks go through the following sequential status updates. Read the description for each status in the list below.

newloginmfabase_parsefull_parsedone

  • new - Task created
  • login - Attempting to log into payroll provider
  • mfa - Attempting to complete multi-factor authentication
  • parse- Attempting to parse payroll data
  • full_parse - Initial parse is done, parsing of slow objects in progress
  • switch_deposit - Direct deposit switching begins
  • done - Task complete

Task errors

View the list below for unsuccessful Task actions. The descriptions below provide additional details for the error states.

  • login_error - Unsuccessful login attempt
  • mfa_error - Incomplete authentication
  • config_error - Configuration issues must be resolved by the user or developer before completing payroll connection
  • account_locked - Locked payroll account
  • unable_to_reset - Incomplete credential reset attempt
  • no_data - No data available from payroll provider
  • unavailable - Payroll provider is unavailable
  • error - Generic error during connection
  • not_supported - Payroll provider or HRIS is not supported at the moment

Data processing stages

Truv processes data using various stages. Large documents and certain formats may require longer median times. View the sections below for descriptions and median processing times.

When using VOIE endpoints, data from login is available without additional processing. For all data, use webhooks or status update API endpoints to track Tasks.

Processing stages

Tasks change status over time through Truv processing. Performance may result in one of the error states below during each respective stage.

NameApproximate time to completeDescription
login< 10 secondsUser authentication with payroll provider
mfa10 - 30 secondsPayroll provider multi-factor authentication request from user
parse~ 30 secondsCollecting all basic information about identity, employment, and list of paystubs with pay dates
full_parse< 45 seconds, up to 5 minutesDownloading and parsing paystubs, W2s, and income sources, data processing is in background after successful authentication and closing Truv Bridge
switch_deposit~ 30 secondsUpdating pay allocations and specified distributions within user account

Median stage times

The stages below process data with the following median times. Processing durations are approximations and may vary.

  • Login - 5 to 15 seconds
  • Base parse - 30 to 60 seconds
  • Full parse - 1 to 5 minutes

📘

Note

Each task has a maximum limit of 20 minutes to complete.