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

<Note>
  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.
</Note>

```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
```

***

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

<Tabs>
  <Tab title="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": ["income"]
    }'
    ```
  </Tab>

  <Tab title="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": ["assets"]
    }'
    ```
  </Tab>

  <Tab title="Income (specific employers)">
    ```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" }
      ]
    }'
    ```
  </Tab>

  <Tab title="Employment">
    ```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"]
    }'
    ```
  </Tab>
</Tabs>

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

<Info>
  For `income` type orders, the refresh can request `income` or `employment` products. For `employment` type orders, the refresh can only request `employment`.
</Info>

<Warning>
  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.
</Warning>

<Tip>
  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.
</Tip>

***

## 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",
  "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'
```

<Note>
  If the refresh fails (e.g., expired session), Truv fires an `order-refresh-failed` [webhook event](/api-reference/webhooks). Handle this by sending the user a new verification link.
</Note>

See [Order object](/api-reference/orders/object) for the full response schema.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Receive notifications when refreshed data is ready
  </Card>

  <Card title="Task Lifecycle" icon="circle-nodes" href="/api-reference/tasks/lifecycle">
    Understand connection status transitions
  </Card>
</CardGroup>