Data Refresh

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 to re-authenticate.

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.

Income
Assets
Income (specific employers)
Employment

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"]
}'

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"]
}'

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" }
  ]
}'

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.

{
  "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.

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. Handle this by sending the user a new verification link.

See Order object for the full response schema.

Next steps

Webhooks

Receive notifications when refreshed data is ready

Task Lifecycle

Understand connection status transitions

​When to use

​Create a data refresh order [Server-side]

​Request fields

​Handle the response

​Next steps

Webhooks

Task Lifecycle

When to use

Create a data refresh order [Server-side]

Request fields

Handle the response

Next steps