> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Task Refresh object

> View information about data refresh endpoints for Links.

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.

1. \[Optional] Subscribe to Webhooks for completed **Task**s with `done` status. Pull payroll data for the data refresh information.
2. Use the [Create a data refresh task](/api-reference/refresh/refresh_task_create) endpoint with the **access\_token** from the original connection.
3. Use webhooks, the [Retrieve a data refresh status](/api-reference/refresh/refresh_task) endpoint, or both to check the status of the refresh.

<Note>
  Each data refresh **Task** is billed individually as a separate verification.
</Note>

## 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.

* [Create a data refresh task](/api-reference/refresh/refresh_task_create)
* [Retrieve a data refresh status](/api-reference/refresh/refresh_task)

***

## Example responses

The JSON objects below are sample responses for the endpoints.

**Create a data refresh**

```json theme={null}
{
  "task_id": "48427a36d43c4d5aa6324bc06c692456"
}
```

**Retrieve a data refresh**

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