Skip to main content

List Bank Accounts

The bank accounts an account holds, each in one fiat currency. Default bank accounts come first, then the rest from oldest to newest. An account that has completed ACH pulls also has a reserve bank account, listed here with kind: reserve.

New in v3: v2 has no equivalent.

A workspace-scoped key lists the whole workspace's bank accounts, or one account's with account_id; an account-scoped key lists its own account's.

Authorization:

Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.

Headers:
  Authorization: APIKey {SIGNED_JWT}

How to build and sign the JWT: Authentication.

Endpoint

GET

/v3/bank-accounts

Query parameters​

ParameterTypeDescription
account_idstring (cst_…)Only this account's bank accounts. An account-scoped key lists its own account and may omit it. A workspace-scoped key that omits it lists every bank account in the workspace.
currencystringOnly bank accounts in this currency: USD, MXN, ARS, COP, BRL or NGN, in upper case.
includestringcustomer adds the holder's customer object to each row. Bank accounts whose account was deleted are then left out of data and total_items.
with_balancebooleantrue adds each bank account's balance.
pageintegerPage number, from 1. Default 1.
limitintegerRows per page. Default 25, at most 100: a larger value is capped at 100 (see Lists).

Response Sample​

{
  "data": [
    {
      "id": "bnk_01k8x4m2qv7r3t5w9y1a3c5e7g",
      "customer_id": "cst_01h455vb4pex5vsknk084sn02q",
      "kind": "deposit",
      "name": "Operating",
      "reference": "ODOPX2",
      "account_number": "555000114019",
      "currency": "USD",
      "status": "active",
      "is_default": true,
      "balance": { "amount": "1250.75", "currency": "USD" },
      "created_at": "2026-03-02T14:20:11Z",
      "updated_at": "2026-09-18T10:05:42Z"
    },
    {
      "id": "bnk_01k8x4p6sx9t5v7x1z3b5d7f9h",
      "customer_id": "cst_01h455vb4pex5vsknk084sn02q",
      "kind": "deposit",
      "name": "Payroll",
      "reference": "K7Q2MZ",
      "account_number": "555000114027",
      "currency": "USD",
      "status": "active",
      "is_default": false,
      "balance": { "amount": "300.00", "currency": "USD" },
      "created_at": "2026-10-01T09:12:30Z",
      "updated_at": "2026-10-01T09:12:30Z"
    }
  ],
  "page": 1,
  "limit": 25,
  "total_items": 2,
  "total_pages": 1
}

This sample was requested with with_balance=true.

Response Schema​

FieldTypeDescription
dataarrayThe bank accounts on this page.
data[].idstring (bnk_…)The bank account.
data[].customer_idstring (cst_…)The account that holds it.
data[].namestringIts name. A bank account that was never named shows as its currency plus account, for example USD account.
data[].referencestringBlockWyre's reference code for the bank account. Bank accounts opened through v3 get a 6-character code of upper-case letters and digits. Empty on a reserve.
data[].account_numberstringThe bank's account number: the number a payer sends money to. Present on every bank account opened through v3; absent on a reserve. On an inactive bank account only the last four digits are shown (xxxx4019). The routing number and bank details a payer also needs are in its deposit instructions.
data[].currencystringUSD, MXN, ARS, COP, BRL or NGN.
data[].kindstringdeposit, a bank account money moves through; or reserve, the account's ACH pull reserve: it only holds, takes no deposit, transfer or withdrawal, and has no reference or account_number.
data[].statusstringactive; pending while the bank has opened it but not activated it yet; or inactive, when it keeps its history but takes no more money.
data[].is_defaultbooleantrue on the bank account money in this currency lands in when no bank account is named. One per currency, never a reserve. See Set the Default Bank Account.
data[].balancemoneyWhat it holds available now; on a reserve, what it holds set aside. Only with with_balance=true. A bank account that was never funded shows "0". For pending amounts, see Balances of One Bank Account.
data[].customerobjectThe holder: id (cst_…), name, email. Only with include=customer.
data[].created_at / updated_atstring (date-time)RFC 3339, UTC.
page, limit, total_items, total_pagesintegerPagination, as described in the API v3 overview. next_cursor and prev_cursor are not returned yet.

A money value is { "amount": "<decimal string>", "currency": "<coin>" }.

Errors​

StatusmessageWhen
400failed to parse requestA parameter has the wrong form: page or limit is not an integer, currency is not one of the listed codes, account_id is not a cst_… id, include is not customer, or with_balance is not a boolean.
401unauthorizedMissing or invalid signature.
403forbiddenAn account-scoped key named another account in account_id.

Support and Resources​

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated​

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!