Skip to main content
Re-verify income and employment at recertification without making clients start over. Use the Order Refresh API to pull updated data from an existing order’s connections — when the session is still active, the client does nothing and Truv returns fresh data. Only clients whose sessions have expired need to re-engage through a verification channel.

​
Refresh workflow

1

Identify the original order

When a case is due for recertification, look up the original Truv order ID associated with the client’s case record.
2

Create a refresh order

Send a POST request to the original order’s endpoint. Specify which product to refresh and, optionally, which employers to include. The refresh creates a new order with its own ID. Omit the employers array to refresh all connections from the original order. See the Data Refresh guide for the full request example.
3

Receive updated data

Listen for the task-status-updated webhook with status: "done" on the new order. Retrieve the refreshed report and pre-fill the caseworker review screen with updated income, employment status, and pay history.

​
When a refresh fails

Truv fires the order-refresh-failed webhook event for any task error status, not only credential problems. Order status alone will not tell you a refresh failed — the order simply stops progressing. Branch on the reported status before deciding what to ask the client to do.
no_data means the provider connected and returned nothing. It is not a verified $0 income. Route these clients to document upload or self-certification rather than recording zero income.
See task error states for the full definition of each status.
OAuth-based payroll connections typically expire after ~180 days. For programs with annual recertification cycles, plan for re-authentication on most renewals. For programs with periodic eligibility reviews, refresh success rates are significantly higher.

​
Refresh limits

  • 1 initial request plus 3 refreshes per access_token in any 24-hour period. See rate limits
  • Each refresh is billed as a separate verification

​
Bulk renewals

For agencies processing many renewals at once, automate refresh order creation by iterating over cases due for recertification. Check each refresh result: if it succeeds, pre-fill the caseworker screen automatically. If it fails, queue the case for a new verification link. See Data Refresh for the full implementation guide, including Bridge Update Mode for re-authentication.

​
Next steps

Caseworker Portal

Send verification links and ingest data into caseworker screens.

Customer Portal

The digital, in-app verification channel.