Skip to main content

Documentation Index

Fetch the complete documentation index at: https://truv.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

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