Create External Account

post

https://api.1money.com/v1/customers/{customer_id}/external-accounts

Create and register a new external bank account for a specific customer.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

⚠️ Important: Customer's Own Account Only

This endpoint is exclusively for adding the customer's own bank account
Do NOT use this endpoint to add third-party or recipient bank accounts
For adding recipient/beneficiary bank accounts, use the Recipients API instead
Incorrect account holder information may result in failed or delayed transfers

Functionality:

Registers a new external bank account that can be used for fiat withdrawals
Accepts US_FEDWIRE, US_ACH, US_RTP, SWIFT, SPEI, LOCAL_BANK_TRANSFER, CHATS, and FPS; availability depends on the account country, currency, customer configuration, and active payment routes
Follow the External Accounts routing-field rules for the selected network
Automatically assigns a unique external_account_id upon successful creation

Idempotency & Duplicate Detection:

Required: Include an Idempotency-Key header with a unique UUID for each new account creation

Path Params

customer_id

string

required

Unique identifier of the customer to associate the account with

Body Params

Request body for creating a new external bank account

network

string

required

Bank network type for the external account.

US_ACH: For US domestic ACH transfers (next-day settlement, lower fees)
US_FEDWIRE: For US domestic wire transfers (same-day settlement)
US_RTP: For US real-time payments (instant settlement)
SWIFT: For international wire transfers via the SWIFT network
SPEI: For Mexican domestic transfers, addressed by an 18-digit CLABE
LOCAL_BANK_TRANSFER: For bank-account transfers over a local clearing network
CHATS: For Hong Kong USD transfers over CHATS
FPS: For Hong Kong HKD and CNY transfers over Faster Payment System (FPS)

nickname

string | null

User-defined nickname or label for the account (optional).
Helps identify the account in listings. Must be 1-64 characters if provided.

account_holder_name

string

required

Full legal name of the account holder (individual or entity).
This is the name registered with the bank for compliance and verification.

currency

string

required

Currency of the bank account (e.g., USD, EUR, GBP).
Must be supported by the selected network type.

country_code

string

enum

required

ISO 3166-1 alpha-3 three-letter country code in uppercase (e.g., USA, GBR, DEU).
Represents the country where the bank account is held. Must be exactly 3 characters.

account_number

string

required

length between 1 and 64

The bank account identifier.

For US_FEDWIRE, US_ACH, and US_RTP: Standard bank account number
For SWIFT international wires with USD: Must be a valid IBAN
For SWIFT with other currencies: Local account number format
For SPEI: 18-digit CLABE
For LOCAL_BANK_TRANSFER: Local bank account number
For CHATS: Hong Kong bank account number
For FPS: Hong Kong branch code followed by the account number, totaling 9-16 digits

institution_id

string | null

The primary institution routing identifier.

For US_FEDWIRE, US_ACH, and US_RTP: 9-digit ABA routing number
For SWIFT: 8 or 11-character SWIFT/BIC code of the destination bank
For SPEI: omit it; the CLABE already encodes its bank in the first three digits
For LOCAL_BANK_TRANSFER: select the applicable canonical institution ID from the
Local Institution ID guide
based on the destination country and currency, then submit it exactly as documented
For CHATS: 8 or 11-character SWIFT/BIC code of the destination bank
For FPS: select the destination bank's three-digit Hong Kong clearing code from the
Local Institution ID guide
based on the destination currency, then submit it exactly as documented

This field is required for LOCAL_BANK_TRANSFER, CHATS, and FPS. For
LOCAL_BANK_TRANSFER and FPS, do not derive or substitute an institution ID; use one of
the canonical values listed in the guide.

institution_name

string | null

Full legal name of the financial institution. For routing-code based networks and
CHATS, it is resolved from institution_id when omitted.

institution_clearing_code

string | null

Additional local or regional routing codes required by specific payment networks or countries.
Examples: Sort codes (UK), BSB numbers (Australia), transit numbers (Canada).
Optional field used when standard institution_id is insufficient for routing.

intermediary_bank

Headers

Idempotency-Key

string

required

UUID v4 for idempotent requests. Prevents duplicate account creation.

Responses

201External account created successfully - Returns the newly created account with assigned external_account_id

400Validation failed - Invalid request body (missing required fields, invalid country code format, nickname too long, invalid routing number format, unsupported currency for network type, or other validation errors)

401Authentication failed - Invalid or missing API key in request header

405Method not allowed - The HTTP method used is not supported for this endpoint

409Conflict - An account with the same idempotency key already exists, or duplicate account with identical banking details detected

422Unprocessable Entity - Invalid enum value (e.g., unsupported network or asset name)

500Internal server error - Unexpected system error occurred during account creation or bank validation