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.

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.

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

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 prompting the user to re-authenticate through Bridge.

See Order 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.

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 for the full returning-user flow.

Next steps

Webhooks

Receive notifications when refreshed data is ready

Task Lifecycle

Understand connection status transitions

Follow-up

Re-engage users who didn’t finish verification

​Refresh vs new order

​When to use

​Create a data refresh order [Server-side]

​Request fields

​Handle the response

​Handle failed refreshes

​Re-authenticate with Bridge Update Mode

​Next steps

Webhooks

Task Lifecycle

Follow-up

Refresh vs new order

When to use

Create a data refresh order [Server-side]

Request fields

Handle the response

Handle failed refreshes

Re-authenticate with Bridge Update Mode

Next steps