Skip to main content
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 RefreshNew Order
User actionNone. Truv reuses existing connections.User must reconnect through Bridge
When to useData is stale but connections are still activeOriginal connections expired, credentials changed, or new employer
Limits3 refreshes per access_token per 24 hours; 5 re-verifications within 90 days for GSENo limit
CostFree for GSE orders (up to 5 within 90 days)Standard pricing
MFAFails if provider requires MFA. User must reconnect.User handles MFA during connection

​
When to use

ScenarioExample
Stale dataOriginal verification is older than your policy window
Updated pay stubsNeed the most recent pay period before closing
Re-verificationUnderwriting requires a fresh pull before final approval
MonitoringPeriodic 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. 
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"]
}'

​
Request fields

FieldTypeDescription
productsarrayProduct to refresh: income, employment, assets, insurance, or transactions. One product per request.
employersarrayEmployers to include. Each object takes id or suborder_number from the original order. Omit to refresh all.
financial_accountsarrayFinancial 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.
StatusCauseResolution
login_errorUser changed their passwordRe-authenticate the user
mfa_errorProvider requires MFA that can’t be completed without the userRe-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