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

# Financial Institutions

> Legacy resource for linking customer bank accounts for withdrawals and deposits. New integrations should use Addresses.

Financial Institutions represent your customer's financial accounts (bank accounts) that can be used to withdraw or receive funds.

<Warning>
  **Legacy / Deprecated:** The Financial Institutions resource is superseded by Addresses. New integrations should create offchain accounts (ACH, wire, RTP) as Addresses and pass their `address_id` to Transfers. Plaid endpoints are now under `/plaid/*`. Existing FI integrations continue to work during a deprecation window.
</Warning>

You can add external accounts through:

1. Financial Institutions API
2. Plaid

## Create through the Financial Institutions API

Link your customer's bank account by adding it to their Account.

**POST** `https://api.brale.xyz/accounts/{account_id}/financial-institutions/external`

```json Request theme={null}
{
  "owner": "Jane Doe",
  "account_number": "1234567890",
  "routing_number": "063108680",
  "beneficiary_address": {
    "street_line_1": "100 Example St",
    "street_line_2": "Suite 500",
    "city": "Springfield",
    "state": "CA",
    "zip": "90001"
  },
  "bank_address": {
    "street_line_1": "100 Example St",
    "street_line_2": "Suite 500",
    "city": "Springfield",
    "state": "CA",
    "zip": "90001"
  },
  "account_type": "checking"
}
```

:::note You can also add Financial Institutions through the Brale Dashboard settings page at [https://app.brale.xyz/settings](https://app.brale.xyz/settings). :::

## Fetching Financial Institutions

Retrieve details of a linked financial institution by ID.

**GET** `https://api.brale.xyz/accounts/{account_id}/financial-institutions/{id}`

```json Response theme={null}
{
  "owner": "Jane Doe",
  "account_number": "****7890",
  "routing_number": "063108680",
  "beneficiary_address": {
    "street_line_1": "100 Example St",
    "street_line_2": "Suite 500",
    "city": "Springfield",
    "state": "CA",
    "zip": "90001"
  },
  "bank_address": {
    "street_line_1": "100 Example St",
    "street_line_2": "Suite 500",
    "city": "Springfield",
    "state": "CA",
    "zip": "90001"
  },
  "account_type": "checking"
}
```

## Create Financial Institutions through Plaid

This guide walks you through how to enable your customers to securely link their bank accounts via Plaid. After linking, the new Financial Institutions can be used for ACH pulls (debits).

### Overview of the Flow

1. Request a Plaid Link Token from Brale.
2. Initialize Plaid Link in your front-end using the `link_token`.
3. Plaid returns a `public_token` once the user successfully links their account.
4. Exchange the `public_token` with Brale to finalize the linking process.
5. Fetch the newly created Financial Institutions for the end user, then proceed with transfers.

### Request a Plaid Link Token

**POST** `https://api.brale.xyz/accounts/{account_id}/financial-institutions/plaid/link_token`

```json Request theme={null}
{
  "date_of_birth": "1990-01-01",
  "email_address": "user@example.com",
  "legal_name": "John Doe",
  "phone_number": "+1234567890"
}
```

All fields above are optional; supply what you collect from the user.

```json Response theme={null}
{
  "link_token": "link_token_XYZ",
  "expiration": "2025-03-23T03:22:34.086Z",
  "callback_url": "https://api.brale.xyz/exchange_public_token/{unique-id}"
}
```

| Parameters     | Description                                                                        |
| -------------- | ---------------------------------------------------------------------------------- |
| `link_token`   | The token you will use to launch Plaid Link in your front-end or mobile app.       |
| `expiration`   | Time at which the `link_token` will no longer be valid.                            |
| `callback_url` | The endpoint to which you should send the `public_token` to finalize the exchange. |

### Render the Plaid Link SDK

In your front-end, initialize Plaid Link using the link\_token you received.

For production apps, it's recommended you send the public\_token to your own backend (over HTTPS), and then have your backend call our exchange endpoint. That way, you avoid exposing your own platform API keys in the browser.

### Register Financial Institution (exchange the public token)

Send us the public\_token you received from Plaid Link. Brale securely exchanges it for a Plaid access\_token server-side and creates/updates a Financial Institution on the specified Account.

**POST** `https://api.brale.xyz/accounts/{account_id}/financial-institutions/register-account`

```json Request theme={null}
{
  "public_token": "public_token_XYZ",
  "customer_webhook_url": "https://mywebhook.com"
}
```

```json Response theme={null}
{
  "financial_institution_id": "fi_123456789"
}
```

After this call completes, our system retrieves the linked bank account and creates a Financial Institution for the account the user selected.

### Check for newly created Financial Institutions

Shortly after exchanging the public token, the user's bank accounts are idempotently created as Financial Institutions which you can query.

**GET** `https://api.brale.xyz/accounts/{account_id}/financial-institutions/{id}`

```json Response theme={null}
{
  "name": "Business Checking Account",
  "transfer_type": ["ACH", "Wire"],
  "bank_details": {
    "owner": "Jane Doe",
    "account_number": "1234567890",
    "routing_number": "987654321",
    "name": "Example Bank",
    "address": {
      "street_line_1": "100 Example St",
      "street_line_2": "Suite 500",
      "city": "Springfield",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "account_type": "checking"
  }
}
```

At this point, you can initiate ACH pulls or other transactions using these new Financial Institutions.

## Handling Re-Authentication

When Plaid signals that an Item requires user action (e.g., credentials changed), Brale can notify you via webhook and you can present a Plaid update Link flow to the user.

### Receive Brale webhook

Brale will `POST` a JSON payload when re-auth is required to the `customer_webhook` you provide during the exchange step.

```json Example payload theme={null}
{
  "reason": "Plaid item requires re-authentication",
  "timestamp": "2025-09-13T17:17:00Z",
  "event_type": "ITEM_LOGIN REQUIRED",
  "financial_institution_id": "fi_id123"
}
```

### Check status

**GET** `https://api.brale.xyz/accounts/{account_id}/financial-institutions/{fi_id}/status`

```json Response theme={null}
{
  "status": "active",
  "last_updated": "2025-09-13T17:17:00Z",
  "financial_institution_id": "fi_id123",
  "needs_update": true
}
```

### Request an updated link token

**POST** `https://api.brale.xyz/accounts/{account_id}/financial-institutions/{fi_id}/update-link-token`

```json Response theme={null}
{
  "link_token": "link_token_XYZ"
}
```

Open Plaid Link again with this `link_token`. Plaid will streamline the flow and only ask the user to re-authenticate. Run Step 3 again with the new `public_token` (same endpoint). The existing Financial Institution is updated in place and retains the same `financial_institution_id`.