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)
US_FEDNOW: For US instant payments over FedNow
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, including INR transfers to Indian bank accounts
CHATS: For Hong Kong USD transfers over CHATS
FPS: For Hong Kong HKD and CNY transfers over Faster Payment System (FPS)
SEPA: For EUR transfers to bank accounts in supported SEPA countries, addressed by IBAN
FASTER_PAYMENT: For GBP transfers to United Kingdom or Jersey bank accounts
UAEFTS: For AED transfers to the United Arab Emirates bank accounts
UPI: For INR transfers to Indian virtual payment addresses

nickname

string | null

User-defined nickname or label for the account (optional).
Helps identify the account in listings. Blank values are treated as omitted.

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, US_RTP, and US_FEDNOW: Standard bank account number
For SWIFT: Account number format depends on the bank country. Germany requires a
valid 22-character DE IBAN; Mexico requires a valid 18-digit CLABE. Both include checksum
validation. United Arab Emirates accounts in USD require a valid 23-character AE IBAN.
For SPEI: 18-digit CLABE
For LOCAL_BANK_TRANSFER: Local bank account number; India requires 9 to 18 ASCII digits
and Japan requires exactly 7 ASCII digits, including leading zeros
For CHATS: Hong Kong bank account number
For FPS: Hong Kong branch code followed by the account number, totaling 9-16 digits
For SEPA: IBAN matching the bank country, without spaces or separators; letters are stored uppercase
For FASTER_PAYMENT: Exactly 8 ASCII digits, preserving leading zeros; no spaces or separators
For UAEFTS: A valid 23-character AE IBAN without spaces or separators
For UPI: VPA in name@handle format, 3 to 50 characters, without spaces

institution_id

string | null

The primary institution routing identifier.

For US_FEDWIRE, US_ACH, US_RTP, and US_FEDNOW: 9-digit ABA routing number
For SWIFT: 8 or 11-character SWIFT/BIC code of the destination bank
For SPEI: not required; the bank code is derived from CLABE. Submitted values are ignored.
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

For SEPA, institution_id, institution_clearing_code, and intermediary_bank are ignored.
For UAEFTS, the bank code is derived from the IBAN in account_number; institution_id is not used.
For FASTER_PAYMENT, institution_id is the required 6-digit sort code, without spaces or separators;
institution_clearing_code and intermediary_bank are ignored.
This field is required for LOCAL_BANK_TRANSFER, CHATS, and FPS.
For India LOCAL_BANK_TRANSFER, supply the 11-character IFSC instead of a catalog bank ID.
For Singapore LOCAL_BANK_TRANSFER in SGD, supply the selected bank's four-digit ABS bank code.
For Japan LOCAL_BANK_TRANSFER in JPY, supply the four-digit bank code and the
three-digit branch code in institution_clearing_code, preserving leading zeros.
For other LOCAL_BANK_TRANSFER destinations and FPS, do not derive or substitute an
institution ID; use one of the canonical values listed in the guide.
For UPI, institution_id, institution_clearing_code, and intermediary_bank are ignored.

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. For SEPA,
FASTER_PAYMENT, India LOCAL_BANK_TRANSFER, and UPI, this is an optional
user-supplied bank name. Routing-code based networks and CHATS allow up to
80 characters; other networks allow up to 128. Blank values are treated as omitted.
For SPEI, UAEFTS, FPS, and LOCAL_BANK_TRANSFER outside India, the bank name
comes from the bank directory. Submitted values are ignored.

institution_clearing_code

string | null

Additional local or regional routing code for SWIFT, required for certain countries.
Required for Japan LOCAL_BANK_TRANSFER in JPY: exactly 3 ASCII digits representing
the branch code (for example, 025). Ignored for other payment networks and destinations.

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