The Task Refresh object

Refresh data from an existing Link with the data refresh endpoints. These let the user bypass entering their payroll credentials a second time.

Perform a data refresh

Follow the steps below to perform a data refresh.

[Optional] Subscribe to Webhooks for completed Tasks with done status. Pull payroll data for the data refresh information.
Use the Create a data refresh task endpoint with the access_token from the original connection.
Use webhooks, the Retrieve a data refresh status endpoint, or both to check the status of the refresh.

Each data refresh Task is billed individually as a separate verification.

Authorization validity

The success of a refresh depends on whether the original connection is still authorized:

Connection type	Typical validity	Notes
OAuth-based (e.g., most payroll providers)	~180 days	Token expires after roughly 6 months. After expiration, the user must re-authenticate through Truv Bridge.
Session-based	Varies by provider	Some providers maintain sessions for weeks, others for months. No fixed guarantee.

For programs with quarterly review cycles, refresh success rates are high because most connections remain active within the 180-day window. For annual review cycles, expect most connections to have expired, requiring the user to re-authenticate.

VOA refreshes from POS integrations

If the initial VOA verification was completed through a point-of-sale integration (e.g., SimpleNexus, Blend), the refresh still works via the Order Refresh API as long as the original connection is active. Use the access_token from the initial order to create the refresh task.

Refresh rate limits

Truv has rate limits on each access_token value. Within a 24-hour period, only an initial request and 3 refreshes are allowed. The Refresh limit for the access_token exceeded error occurs for any requests outside of the interval and limit.

Attributes

The sections below cover values from Data Refresh endpoints.

Data refresh task

The information below is for the response from data refresh tasks for a Link.

Attribute	Type	Description
task_id	string	Unique ID for Link data refresh task

Data refresh status

The values in the table below are for the status of a data refresh.

Attribute	Type	Description
id	string	Unique refresh task ID
created_at	string	Time when refresh task was created
refresh_date	string	~~Date of data refresh~~ (Deprecated, invalid datetime format)
status	string	Data refresh task status

Endpoints

These endpoints are from the Data refresh API.

Example responses

The JSON objects below are sample responses for the endpoints. Create a data refresh

{
  "task_id": "48427a36d43c4d5aa6324bc06c692456"
}

Retrieve a data refresh

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "created_at": "2021-04-06T11:30:00Z",
  "refresh_date": "2020-03-10",
  "status": "new"
}

​Perform a data refresh

​Authorization validity

​VOA refreshes from POS integrations

​Refresh rate limits

​Attributes

​Data refresh task

​Data refresh status

​Endpoints

​Example responses

Perform a data refresh

Authorization validity

VOA refreshes from POS integrations

Refresh rate limits

Attributes

Data refresh task

Data refresh status

Endpoints

Example responses