---
updatedAt: 2026-05-20T22:03:31.000Z
agentTools:
  projectIndex: https://docs.spinwheel.io/llms.txt
---

# Bank Account Real-Time Balances

# Overview

Spinwheel's Bank Account Real-Time Balance product provides you with key insight about a user's bank account. Please review our best practices for utilizing this product below!

# Sandbox Test Data

Use the following test data in order to test **successfully** creating a bank account, and getting the realtime balance:

```
{
    "routingNumber": "121000248",
    "accountNumber": "001875060663",
    "telephoneBankingPin": "0000",
    "accountType": "CHECKING"
}
```

Use the following test data to test a `NOT_SUPPORTED` institution.

```
{
    "routingNumber": "21001208",
    "accountNumber": "001122060415",
    "telephoneBankingPin": "0000",
    "accountType": "CHECKING"
}
```

<br />

# Step 1: Add a Bank Account

The first step is to [add a bank account](https://docs.spinwheel.io/reference/create-bank-account). Include the relevant routing number and account number. It is recommended to also include the account type and telephone banking pin for maximum coverage. When using the sandbox environment, please use the [sandbox test data](https://docs.spinwheel.io/docs/bank-account-real-time-balances#sandbox-test-data) .

## Determining Eligibility

Included in the response from the request to add a bank account (as well as the  [/v1/users endpoint](https://docs.spinwheel.io/reference/get-user-profile) ) is the  <Glossary>capabilities matrix</Glossary> . We recommend confirming that the newly added bank account is supported for real-time balances prior to attempting to fetch it.

The following is an example of what could be seen on a bank account that is `SUPPORTED` for real-time balances.

```
{
  ...
  "data": {
    ...
    "capabilities": {
      "payments": {
        "billPayment": {
          "availability": "SUPPORTED"
        },
        "receiveOnlyPayment": {
          "availability": "SUPPORTED"
        }
      },
      "data": {
        "realtimeBalance": {
          "availability": "SUPPORTED" <-- ✅
        }
      }
    }
  }
}
```

Reasons the real-time balance may be `NOT_SUPPORTED`:

* `INSTITUTION_NOT_SUPPORTED`
* `INSTITUTION_DISABLED`
* `REFRESH_EXHAUSTED`
* `NOT_PRIMARY_ACCOUNT_HOLDER`
* `ACCOUNT_TERMINATED`
* `CLOSED_ACCOUNT_NO_BALANCE`
* `CLOSED_ACCOUNT`
* `ACCOUNT_NUMBER_VERIFICATION_FAILED`

# Step 2: Initiate a Bank Account Balance Lookup

Once a bank account is created, you can simply call to [look up the real-time balance](https://docs.spinwheel.io/reference/request-bank-account-data), by using the userId and bankAccountId. Once this request is made, the status of the look up will be `IN_PROGRESS`. You may also notice that once a real-time balance request is made, the `realtimeBalance.availability` will be `NOT_SUPPORTED` to prevent multiple concurrent requests for a single bank account.

# Step 3: Retrieve the Balance

In order to retrieve the bank account's balance, we recommend registering a webhook, you can [read more on that here](https://docs.spinwheel.io/docs/webhooks#bank_account_lookup_status_change). Alternatively you may poll for changes in status [using this endpoint](https://docs.spinwheel.io/docs/webhooks#bank_account_lookup_status_change).