---
title: "Update an External Account"
method: PATCH
path: "/external-accounts/{externalAccountId}"
tags: ["ExternalAccount"]
---

# Update an External Account

`PATCH /external-accounts/{externalAccountId}`

Update an External Account. Only `label` and `metadata` are mutable; any
other JSON key in the body is rejected with 400.

## Path parameters

- `externalAccountId` string, required

## Request body

- ExternalAccountUpdateRequest — Partial update - only `label` and `metadata` are mutable. Financial / identity fields are immutable (re-pointing a destination is create-new + re-point). Any other JSON key in the body is rejected with 400.
  - `label` string — Optional display label.
  - `metadata` object — Free-form key-value pairs stored on the resource and echoed back on reads.

## Response `200`

The request has succeeded.

- ExternalAccount — A saved payment destination registered for a customer or one of their counterparties. Exactly one of the per-type response detail objects is populated, selected by `type`. Write-only secrets (full account number, full IBAN) are never present on reads - only their last-4 renderings.
  - `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)