Data Refresh Mode

To initiate data refresh for the existing Link you need to trigger it from the backend using the following endpoint. Truv will try to refresh the data from an existing Link without requiring the user to enter their payroll credentials a second time. Use webhooks or poll backend endpoint to check the status of the refresh Task.


Refresh status might fall into the error state in case user changed their password or their session expired.

Authentication issues

A session is created when a user logs into a web service. Such session can last for any period of time, which - in our case - is typically determined by the payroll system you are connecting with. While the session is still active, the data can be refreshed automatically.

Data refresh authentication issues are likely to happen for the following reasons:

  1. Change in login credentials such as a change in username or password. This situation will be evident by the /refresh/tasks/{task_id}/ endpoint returning a login_error value for the status field.

  2. Error in multi-factor authentication. This is likely to occur when Truv is presented with an MFA question the user hasn't answered yet, or with MFA scenarios where a unique code is provided by an authenticator app or via email/SMS. You'll know when an MFA error occurs by the /refresh/tasks/{task_id}/ endpoint returning an mfa_error value for the status field.

Handling data refresh authentication issues

When you attempt a data refresh and are presented with either the login_error or mfa_error status, typically you would want to present the user with the chance to re-authenticate with their payroll provider.

To do this, you need to create a new bridge_token by calling the Bridge Token endpoint passing the same access_token used when attempting to perform a data refresh in the body of the Refresh data request.

Initializing Bridge with this new bridge_token will take the applicant through the re-authentication process so your application can access the most recent data provided by the payroll provider. It's important to note that when the applicant re-authenticates this also pulls the latest data from the payroll provider.

Once the callback from Bridge returns success status, the fresh data can be pulled from the backend.