GuidesRecipesAPI ReferenceChangelog
Guides
  1. Customer management

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.

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

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 endpoint
to finalize the refresh:

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
endpoint:

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