---
title: "List External Accounts"
method: GET
path: "/external-accounts"
tags: ["ExternalAccount"]
---

# List External Accounts

`GET /external-accounts`

List External Accounts. Both `customerId` and `counterpartyId` are optional
filters - omit both to list all external accounts in the project (still
tenant-scoped by project).

## Query parameters

- `limit` integer
- `startingAfter` string
- `endingBefore` string
- `customerId` string
- `counterpartyId` string

## Response `200`

The request has succeeded.

- ExternalAccountList — Paginated list of ExternalAccount resources.
  - `object` string — Resource type discriminator.
  - `hasMore` boolean — True when more rows exist beyond this page in the direction of travel (forward by default, backward when `endingBefore` was supplied).
  - `nextCursor` string — Opaque cursor pointing at the last item in this page. Present when `data` is non-empty. Pass as `startingAfter` to fetch the next page; `hasMore=false` signals no more pages forward.
  - `previousCursor` string — Opaque cursor pointing at the first item in this page. Present when `data` is non-empty. Pass as `endingBefore` to page backward; when this yields an empty response the client is at the start of the list.
  - `data` ExternalAccount[] — The page of results.
    - `id` string — Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired.
    - `object` 'externalAccount' — Resource type discriminator. Always "externalAccount".
    - `owner` union — Who owns the External Account.
      - object — Customer-owned External Account.
        - `kind` 'customer', required — Owner kind discriminator.
        - `customerId` string, required — Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired.
      - object — Counterparty-owned External Account (an address-book entry).
        - `kind` 'counterparty', required — Owner kind discriminator.
        - `counterpartyId` string, required — Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired.
    - `type` 'bankUs' | 'bankIban' | 'bankCanada' | 'card' | 'walletExternal' — External Account type. `card` is created only via the dedicated `POST /external-accounts/cards` endpoint; supplying `type = card` to the generic create is rejected with 422 `cardMustUseCardEndpoint`. `card` and `walletExternal` remain valid for reads, lists, get and delete.
    - `category` 'fiatAccount' | 'crypto' — Coarse classification derived from `type`, stored for query convenience.
    - `status` 'active' | 'pending' | 'rejected' | 'invalid' | 'deleted' | 'failed' — Lifecycle of an External Account. `pending → active` on successful provisioning; `pending → failed` on upstream rejection or provisioning timeout. `rejected` (create-time country screening) and `invalid` (derived from payout returns) are reserved enum values with no transition logic in this slice. `deleted` is the soft-delete terminal.
    - `failureReason` 'ereborRejected' | 'cardProviderRejected' | 'providerAccountMissing' | 'cardLimitReached' | 'cardInUse' | 'provisioningTimeout' | 'systemError' — Closed enum stamped on an External Account when `status = failed`.
    - `failureDetail` ProviderRejectionDetail — Structured, partner-safe description of a terminal provider rejection. Populated alongside a `failed` status so the rejection reason is visible without support/log access. The same object is returned as the `details` field of the `422` error body when a create is terminally rejected by the provider.
      - `provider` string — Provider that rejected the request.
      - `code` string — Vendor machine-readable error code (e.g. `INVALID_REQUEST`).
      - `message` string — Vendor human-readable message.
      - `details` string[] — Per-field validation messages, each in `field: message` form.
      - `providerRequestId` string — Vendor request id, for support escalation.
    - `rejectionReason` string — Set when status = `rejected` (compliance screening).
    - `invalidReason` string — Set when `status = invalid` (derived from payout returns). Free-text for now; a closed enum lands with the invalidation transition logic.
    - `label` string — Optional display label.
    - `metadata` object — Free-form key-value pairs supplied at creation or update.
    - `bankUs` ExternalAccountBankUsResponse — bankUs response detail. The full account number is never echoed - only its last four digits.
      - `accountNumberLast4` string, required — Last four digits of the US bank account number.
      - `routingNumber` string, required — Nine-digit ABA routing number (not a secret).
      - `accountType` 'checking' | 'savings' — Bank account sub-type for US accounts.
      - `bankName` string — Bank display name.
    - `bankIban` ExternalAccountBankIbanResponse — bankIban response detail. The full IBAN is never echoed - only its last four characters.
      - `ibanLast4` string, required — Last four characters of the IBAN.
      - `BIC` string, required — SWIFT BIC (8 or 11 chars).
      - `bankAddress` Address — A postal address. country is an ISO 3166-1 alpha-2 country code.
        - `line1` string — Street address, line 1.
        - `line2` string — Street address, line 2.
        - `city` string — City.
        - `state` string — State / province / region.
        - `country` string — ISO 3166-1 alpha-2
        - `zipCode` string — ZIP / postal code.
      - `countryCode` string, required — ISO 3166-1 alpha-2; derived from the IBAN prefix when not supplied.
    - `bankCanada` ExternalAccountBankCanadaResponse — bankCanada response detail. The full account number is never echoed - only its last four digits.
      - `institutionNumber` string, required — Three-digit institution number.
      - `transitNumber` string, required — Five-digit transit number.
      - `accountNumberLast4` string, required — Last four digits of the Canadian bank account number.
      - `bankName` string — Bank display name.
    - `walletExternal` ExternalAccountWalletExternalResponse — walletExternal response detail. The blockchain address is public, so it is echoed as submitted.
      - `blockchainAddress` string, required — The registered blockchain address, as submitted.
      - `networkFamily` 'evm' | 'solana', required — Crypto network family for a registered external wallet. A walletExternal is registered per family (an EVM address is valid across every EVM chain); the service provisions one counterparty blockchain address per served network in the family.
      - `custodian` 'ANCHORAGE_SG' | 'ANCHORAGE_US' | 'AQUANOW_CA' | 'B2C2_UK' | 'B2C2_US' | 'BITGO_SG' | 'BITGO_US' | 'BITSTAMP_US' | 'BVNK_US' | 'CIRCLE_FR' | 'CIRCLE_US' | 'CITIBANK_US' | 'COINBASE_US' | 'COINSMART_CA' | 'COPPER_CH' | 'COPPER_UK' | 'CUMBERLAND_DRW_LLC_US' | 'CUMBERLAND_SG' | 'EREBOR_BANK_US' | 'FALCONX_US' | 'FIDELITY_UK' | 'FIDELITY_US' | 'FIREBLOCKS_APAC' | 'FIREBLOCKS_US' | 'GALAXY_KY' | 'GEMINI_US' | 'KRAKEN_BVI' | 'KRAKEN_EU_IE' | 'KRAKEN_UK' | 'KRAKEN_US' | 'NUBANK_BR' | 'PAXOS_US' | 'RAMP_NETWORK_US' | 'ROBINHOOD_US' | 'WINTERMUTE_GB' | 'SELF_HOSTED' | 'OTHER', required
      - `otherCustodian` string — Set when `custodian = OTHER`.
      - `supportedDestinations` SupportedDestination[] — The (asset, network) pairs this wallet can receive, derived from `networkFamily` (`{usdc, usdt}` across the family's served networks).
        - `asset` string, required — Stablecoin symbol, e.g. `usdc` / `usdt`.
        - `network` string, required — Network the asset can be delivered on, e.g. `ethereum` / `base` / `solana`.
    - `card` ExternalAccountCardResponse — card response detail. Last-4 + expiry only; PAN/CVV are never stored or returned. `cardProvider` (brand) and `cardType` are derived server-side from the PAN and are response-only.
      - `cardNumberLast4` string — Last four digits of the card PAN.
      - `cardProvider` 'visa' | 'mastercard' | 'amex' | 'discover' — Card network/brand. Derived server-side from the PAN; never accepted on a request.
      - `cardType` 'debit' | 'credit' | 'prepaid' — Card funding type, derived server-side from the PAN. Only `debit` is supported today; `credit` and `prepaid` are reserved for future push-to-card / pull-from-card support.
      - `expiryMonth` integer — Card expiry month (MM).
      - `expiryYear` integer — Card expiry year (YYYY).
      - `billingAddressSource` 'provided' | 'customerDefault' — Where a card's billing address came from. `provided` = supplied on the request; `customerDefault` = filled from the owning customer's address because the request omitted it.
    - `resolvedTransactions` TypeId[] — Transaction ids that this registration submitted for sender-attribution release. Returned ONLY on the POST create response, and only when registering this walletExternal matched held inbounds. Attribution is async: each entry is submitted to the provider from `awaitingAction.awaitingSenderAttribution` and moves to `processing.fundsPulled` once settlement confirms - so an immediate GET of an id may still show `awaitingAction`. Omitted on GETs (the create path is the only writer).
    - `createdAt` string, date-time — When the external account was registered.
    - `updatedAt` string, date-time — When the external account was last updated.

---

[API](https://skmtc.net/polygon-technology/apis/polygon-oms-public-api.md) · [All operations](https://skmtc.net/polygon-technology/apis/polygon-oms-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polygon-technology/polygon-oms-public-api/revisions/18fdaebf64e5/schema)