> ## 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.
# Data Refresh
> Refresh verification data from a completed order without requiring the user to reconnect
Create a data refresh order to pull updated income, employment, or asset data from an existing order's connections. The user does not need to re-authenticate. Truv reuses the existing account links.
Data refresh works only when the original account connections are still active. If a connection has expired or the user changed their credentials, use [Bridge Update Mode](/developers/integration/bridge-widget/returning-user) to re-authenticate.
```mermaid theme={null}
sequenceDiagram
participant Server as Your Server
participant API as Truv API
Server->>API: Create refresh order (POST /v1/orders/{id}/)
API-->>Server: New order_id
Note over API: Truv pulls fresh data from existing connections
API-->>Server: Webhook (task-status-updated, done)
Server->>API: Retrieve refreshed order (GET /v1/orders/{new_id}/)
API-->>Server: Updated employer data, reports
```
***
## Refresh vs new order
| | Data Refresh | New Order |
| --------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **User action** | None. Truv reuses existing connections. | User must reconnect through Bridge |
| **When to use** | Data is stale but connections are still active | Original connections expired, credentials changed, or new employer |
| **Limits** | 3 refreshes per access\_token per 24 hours; 5 re-verifications within 90 days for GSE | No limit |
| **Cost** | Free for GSE orders (up to 5 within 90 days) | Standard pricing |
| **MFA** | Fails if provider requires MFA. User must reconnect. | User handles MFA during connection |
***
## When to use
| Scenario | Example |
| ----------------- | -------------------------------------------------------- |
| Stale data | Original verification is older than your policy window |
| Updated pay stubs | Need the most recent pay period before closing |
| Re-verification | Underwriting requires a fresh pull before final approval |
| Monitoring | Periodic income checks on active loans |
***
## Create a data refresh order \[Server-side]
Send a `POST` request to the original order's endpoint. Specify which `products` to refresh and optionally which `employers` or `financial_accounts` to include.
```bash theme={null}
curl --request POST \
--url https://prod.truv.com/v1/orders/39aa1486ccca4bc19cda071ffc1ba392/ \
--header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
--header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
--header 'Content-Type: application/json' \
--data '{
"products": ["income"]
}'
```
```bash theme={null}
curl --request POST \
--url https://prod.truv.com/v1/orders/39aa1486ccca4bc19cda071ffc1ba392/ \
--header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
--header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
--header 'Content-Type: application/json' \
--data '{
"products": ["assets"]
}'
```
```bash theme={null}
curl --request POST \
--url https://prod.truv.com/v1/orders/39aa1486ccca4bc19cda071ffc1ba392/ \
--header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
--header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
--header 'Content-Type: application/json' \
--data '{
"products": ["income"],
"employers": [
{ "id": "ad9f14440d624ec3b0f66e81e44518c7" }
]
}'
```
```bash theme={null}
curl --request POST \
--url https://prod.truv.com/v1/orders/39aa1486ccca4bc19cda071ffc1ba392/ \
--header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
--header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
--header 'Content-Type: application/json' \
--data '{
"products": ["employment"]
}'
```
### Request fields
| Field | Type | Description |
| -------------------- | ----- | --------------------------------------------------------------------------------------------------------------- |
| `products` | array | Product to refresh: `income`, `employment`, `assets`, `insurance`, or `transactions`. One product per request. |
| `employers` | array | Employers to include. Each object takes `id` or `suborder_number` from the original order. Omit to refresh all. |
| `financial_accounts` | array | Financial accounts to include. Each object takes `id` or `suborder_number`. Omit to refresh all. |
For `income` type orders, the refresh can request `income` or `employment` products. For `employment` type orders, the refresh can only request `employment`.
The refresh creates a **new order** with a new `id`. Use this new order ID for all subsequent operations — the original order ID is not updated.
If you pass an `order_number` when creating the original order, it persists through to the refresh order. Use this to correlate refresh orders with your internal tracking system.
***
## Handle the response
Listen for the `order-status-updated` webhook to know when the refreshed data is ready.
```json theme={null}
{
"webhook_id": "17a80437ce23411dbfd656694d19a8c6",
"event_type": "order-status-updated",
"event_created_at": "2024-07-11T21:43:08.073930Z",
"order_id": "NEW_ORDER_ID",
"status": "completed",
"updated_at": "2024-07-11T21:43:08.075540+00:00"
}
```
Retrieve the refreshed data using the new order ID.
```bash theme={null}
curl --request GET \
--url https://prod.truv.com/v1/orders/NEW_ORDER_ID/ \
--header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
--header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
--header 'Accept: application/json'
```
If the refresh fails (e.g., expired session), Truv fires an `order-refresh-failed` [webhook event](/api-reference/webhooks). Handle this by prompting the user to re-authenticate through Bridge.
See [Order object](/api-reference/orders/object) for the full response schema.
***
## Handle failed refreshes
Refreshes can fail when the user's credentials have changed or the provider requires MFA. Check the task status in the webhook payload.
| Status | Cause | Resolution |
| ------------- | -------------------------------------------------------------- | ------------------------ |
| `login_error` | User changed their password | Re-authenticate the user |
| `mfa_error` | Provider requires MFA that can't be completed without the user | Re-authenticate the user |
Other common failure causes:
* **OAuth token expired (\~180 days)**: Financial institutions using OAuth typically expire tokens after \~180 days. The user must reconnect.
* **Provider unavailable**: The payroll provider may be temporarily down. Retry after some time.
* **Account locked**: Too many failed attempts may have locked the user's account at the provider. The user needs to unlock it with the provider first.
### Re-authenticate with Bridge Update Mode
Create a new bridge token using the `access_token` from the original connection, then initialize Truv Bridge for the user to re-authenticate.
```bash theme={null}
curl -X POST https://prod.truv.com/v1/users/{user_id}/tokens/ \
-H "X-Access-Client-Id: YOUR_TRUV_CLIENT_ID" \
-H "X-Access-Secret: YOUR_TRUV_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"product_type": "income",
"access_token": "ACCESS_TOKEN_FROM_ORIGINAL_CONNECTION"
}'
```
Pass the new `bridge_token` to your frontend and re-initialize Bridge. The user logs in again, and fresh data becomes available through the existing Link.
Sessions are determined by the payroll provider. Data refreshes succeed automatically during active sessions. If the session has expired, re-authentication is required.
See [Bridge Update Mode](/developers/integration/bridge-widget/returning-user) for the full returning-user flow.
***
## Next steps
Receive notifications when refreshed data is ready
Understand connection status transitions
Re-engage users who didn't finish verification