---
updatedAt: 2026-08-31T13:02:51.000Z
agentTools:
  projectIndex: https://docs.cybrid.xyz/llms.txt
---

# Refresh External Bank Accounts

How do I refresh an expired Plaid bank connection?

## Overview

Plaid bank connections expire periodically and require the customer to re-authenticate with their financial institution. When a connection expires, the external bank account's `state` transitions to `refresh_required` and the account cannot be used for transactions until the customer completes Plaid's Update Mode flow.

> ❗️ Transactions disabled
>
> No transactions can be performed with an external bank account in the `refresh_required` state.

## Detect the refresh\_required state

Poll `GET /api/external_bank_accounts/{external_bank_account_guid}` and check the `state` field.

```json Response
{
  "guid": "external_bank_account_guid",
  "name": "Customer Checking Account",
  "asset": "USD",
  "account_kind": "plaid",
  "bank_guid": "bank_guid",
  "customer_guid": "customer_guid",
  "state": "refresh_required",
  "failure_code": null,
  "created_at": "2026-01-01T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

## Refresh the bank connection

Guide the customer through Plaid's Update Mode in five steps:

1. **Detect** the `refresh_required` state by polling `GET /api/external_bank_accounts/{external_bank_account_guid}`.
2. **Create a workflow** with `POST /api/workflows` using `kind: link_token_update` and the `external_bank_account_guid` that needs to be refreshed. Read the `plaid_link_token` from the response.
3. **Initialize Plaid Link** with the `plaid_link_token` in update mode.
4. The customer **re-authenticates** with their financial institution through the Plaid Link flow.
5. **Update the external bank account state** by calling `PATCH /api/external_bank_accounts/{external_bank_account_guid}` with `state` set to `completed`.

> ⚠️ Manual state update required
>
> The Platform does not automatically update the external bank account state after the customer re-authenticates. Your application must explicitly call `PATCH /api/external_bank_accounts/{external_bank_account_guid}` with `{ "state": "completed" }` to transition the account out of the `refresh_required` state.

### Create the update workflow

```http Request
POST /api/workflows
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "plaid",
  "kind": "link_token_update",
  "language": "en",
  "link_customization_name": "default",
  "external_bank_account_guid": "external_bank_account_guid",
  "redirect_uri": "https://yourapp.com/api/plaid-redirect-uri"
}
```

### Finalize the refresh

After the customer completes the Plaid Link update flow, call the [patch external bank account](https://docs.cybrid.xyz/reference/patchexternalbankaccount) endpoint to finalize the refresh:

```http Request
PATCH /api/external_bank_accounts/{external_bank_account_guid}
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "state": "completed"
}
```

## Sandbox testing

To test the full update mode flow, force an external bank account into the `refresh_required` state using the [patch external bank account](https://docs.cybrid.xyz/reference/patchexternalbankaccount) endpoint:

```http Request
PATCH /api/external_bank_accounts/{external_bank_account_guid}
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "state": "refresh_required"
}
```

This simulates an expired bank connection so you can verify that your application handles the update mode flow correctly.

## Next steps

* [Add Customer External Bank Accounts](https://docs.cybrid.xyz/docs/add-customer-external-bank-accounts)
* [Verify External Bank Accounts](https://docs.cybrid.xyz/docs/verifying-external-bank-accounts)
* [Transfer Process](https://docs.cybrid.xyz/docs/transfer-process)