> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Renewals

> Re-verify income and employment for clients renewing their benefits at recertification

Re-verify income and employment at recertification without making clients start over. Use the [Order Refresh API](/api-reference/orders/orders_create_refresh_order) 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](/developers/integration/embedded-orders/data-refresh#create-a-data-refresh-order-server-side) for the full request example.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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](/government/integration/overview).

| Scenario                 | Cause                                              | What to do                                                                         |
| ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Session expired**      | Payroll provider session timed out or requires MFA | Create a new order and send a fresh verification link through your renewal process |
| **Credentials changed**  | Client changed their payroll login password        | Create a new order — the client re-authenticates through Bridge                    |
| **Provider unavailable** | Payroll provider is temporarily down               | Retry the refresh after some time                                                  |

<Note>
  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.
</Note>

***

## 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](/developers/integration/embedded-orders/data-refresh) for the full implementation guide, including [Bridge Update Mode](/developers/integration/bridge-widget/returning-user) for re-authentication.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Caseworker Portal" icon="user-tie" href="/government/integration/caseworker-portal">
    Send verification links and ingest data into caseworker screens.
  </Card>

  <Card title="Customer Portal" icon="desktop" href="/government/integration/customer-portal">
    The digital, in-app verification channel.
  </Card>
</CardGroup>