Refresh data from an existing Link with the data refresh endpoints. These let the user bypass entering their payroll credentials a second time.
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. |
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"
}
{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"created_at": "2021-04-06T11:30:00Z",
"refresh_date": "2020-03-10",
"status": "new"
}
