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

Refreshes fail when the client’s session has expired or their credentials have changed. The webhook returns login_error or mfa_error. Re-engage the client through any verification channel.
ScenarioCauseWhat to do
Session expiredPayroll provider session timed out or requires MFACreate a new order and send a fresh verification link through your renewal process
Credentials changedClient changed their payroll login passwordCreate a new order — the client re-authenticates through Bridge
Provider unavailablePayroll provider is temporarily downRetry the refresh after some time
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

  • 3 refreshes per connection per 24-hour period
  • 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.