Sign in

v1

latestOpenAPI 3.1.0Proprietary2026-07-2464170247.4 KB
External Accounts (Withdraw to Self)

Create External Account

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

⚠️ 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
  • Supports multiple bank networks: US Fedwire, US ACH, US RTP, and SWIFT international wires
  • 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
post/v1/customers/{customer_id}/external-accounts

Path parameters

customer_idstring required

Unique identifier of the customer to associate the account with

Headers

Idempotency-Keystring required

UUID v4 for idempotent requests. Prevents duplicate account creation.

Request body

networkstring required

Bank network type for the external account. External account creation supports standard bank networks only.

  • US_FEDWIRE: For US domestic wire transfers (same-day settlement)
  • US_ACH: For US domestic ACH transfers (next-day settlement, lower fees)
  • US_RTP: For US real-time payments (instant settlement)
  • SWIFT: For international wire transfers via the SWIFT network
nicknamestring nullable

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

account_holder_namestring required

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

currencystring required

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

country_code'AND' | 'ARE' | 'AFG' | 'ATG' | 'AIA' | 'ALB' | 'ARM' | 'AGO' | 'ARG' | 'ASM' | 'AUT' | 'AUS' | 'ABW' | 'AZE' | 'BIH' | 'BRB' | 'BGD' | 'BEL' | 'BFA' | 'BGR' | 'BHR' | 'BDI' | 'BEN' | 'BLM' | 'BMU' | 'BRN' | 'BOL' | 'BRA' | 'BHS' | 'BTN' | 'BWA' | 'BLR' | 'BLZ' | 'CAN' | 'CCK' | 'COD' | 'CAF' | 'COG' | 'CHE' | 'CIV' | 'COK' | 'CHL' | 'CMR' | 'CHN' | 'COL' | 'CRI' | 'CUB' | 'CPV' | 'CUW' | 'CXR' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DNK' | 'DMA' | 'DOM' | 'DZA' | 'ECU' | 'EST' | 'EGY' | 'ESH' | 'ERI' | 'ESP' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FSM' | 'FRO' | 'FRA' | 'GAB' | 'GBR' | 'GRD' | 'GEO' | 'GUF' | 'GGY' | 'GHA' | 'GIB' | 'GRL' | 'GMB' | 'GIN' | 'GLP' | 'GNQ' | 'GRC' | 'SGS' | 'GTM' | 'GUM' | 'GNB' | 'GUY' | 'HKG' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IRL' | 'ISR' | 'IMN' | 'IND' | 'IOT' | 'IRQ' | 'IRN' | 'ISL' | 'ITA' | 'JEY' | 'JAM' | 'JOR' | 'JPN' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'COM' | 'KNA' | 'PRK' | 'KOR' | 'KWT' | 'CYM' | 'KAZ' | 'LAO' | 'LBN' | 'LCA' | 'LIE' | 'LKA' | 'LBR' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'LBY' | 'MAR' | 'MCO' | 'MDA' | 'MNE' | 'MAF' | 'MDG' | 'MHL' | 'MKD' | 'MLI' | 'MMR' | 'MNG' | 'MAC' | 'MNP' | 'MTQ' | 'MRT' | 'MSR' | 'MLT' | 'MUS' | 'MDV' | 'MWI' | 'MEX' | 'MYS' | 'MOZ' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NIU' | 'NZL' | 'OMN' | 'PAN' | 'PER' | 'PYF' | 'PNG' | 'PHL' | 'PAK' | 'POL' | 'SPM' | 'PCN' | 'PRI' | 'PSE' | 'PRT' | 'PLW' | 'PRY' | 'QAT' | 'REU' | 'ROU' | 'SRB' | 'RUS' | 'RWA' | 'SAU' | 'SLB' | 'SYC' | 'SDN' | 'SWE' | 'SGP' | 'SHN' | 'SVN' | 'SJM' | 'SVK' | 'SLE' | 'SMR' | 'SEN' | 'SOM' | 'SUR' | 'SSD' | 'STP' | 'SLV' | 'SXM' | 'SYR' | 'SWZ' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TLS' | 'TKM' | 'TUN' | 'TON' | 'TUR' | 'TTO' | 'TUV' | 'TWN' | 'TZA' | 'UKR' | 'UGA' | 'USA' | 'URY' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'MYT' | 'ZAF' | 'ZMB' | 'ZWE' required

ISO 3166-1 alpha-3 country codes.

account_numberstring required

The bank account identifier.

  • For US domestic networks (FEDWIRE/ACH/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
institution_idstring required

The primary institution routing identifier.

  • For US domestic networks (FEDWIRE/ACH/RTP): 9-digit ABA routing number
  • For SWIFT international wires: 8 or 11-character SWIFT/BIC code of the destination bank
institution_clearing_codestring nullable

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.

Example request

{
  "network": "SWIFT",
  "nickname": "Primary Operating Account",
  "account_holder_name": "TechStart Holdings LLC",
  "currency": "USD",
  "account_number": "4447891623",
  "institution_id": "DEUTDEFF",
  "institution_clearing_code": "021000021",
  "intermediary_bank": {
    "institution_id": "PNBPUS3NNYC"
  }
}

Response

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

external_account_idstring required

Unique identifier for the external account (UUID format). Use this ID for all subsequent operations (retrieve, delete, withdrawals).

idempotency_keystring required

HTTP Idempotency-Key header value. Stricter than other IDs: ≤64 ASCII chars per the common REST API convention.

customer_idstring required

Portfolio ID — also exposed as customer_id in OpenAPI. Identifies one individual application / portfolio row within an entity.

status'PENDING' | 'APPROVED' | 'FAILED' required
networkstring required
nicknamestring required

User-defined nickname or label for the account (optional). Helps identify the account in listings.

account_holder_namestring required

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

currencystring required
  • Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported)
  • Digital assets: BTC
  • Fiat currencies: USD
country_code'AND' | 'ARE' | 'AFG' | 'ATG' | 'AIA' | 'ALB' | 'ARM' | 'AGO' | 'ARG' | 'ASM' | 'AUT' | 'AUS' | 'ABW' | 'AZE' | 'BIH' | 'BRB' | 'BGD' | 'BEL' | 'BFA' | 'BGR' | 'BHR' | 'BDI' | 'BEN' | 'BLM' | 'BMU' | 'BRN' | 'BOL' | 'BRA' | 'BHS' | 'BTN' | 'BWA' | 'BLR' | 'BLZ' | 'CAN' | 'CCK' | 'COD' | 'CAF' | 'COG' | 'CHE' | 'CIV' | 'COK' | 'CHL' | 'CMR' | 'CHN' | 'COL' | 'CRI' | 'CUB' | 'CPV' | 'CUW' | 'CXR' | 'CYP' | 'CZE' | 'DEU' | 'DJI' | 'DNK' | 'DMA' | 'DOM' | 'DZA' | 'ECU' | 'EST' | 'EGY' | 'ESH' | 'ERI' | 'ESP' | 'ETH' | 'FIN' | 'FJI' | 'FLK' | 'FSM' | 'FRO' | 'FRA' | 'GAB' | 'GBR' | 'GRD' | 'GEO' | 'GUF' | 'GGY' | 'GHA' | 'GIB' | 'GRL' | 'GMB' | 'GIN' | 'GLP' | 'GNQ' | 'GRC' | 'SGS' | 'GTM' | 'GUM' | 'GNB' | 'GUY' | 'HKG' | 'HND' | 'HRV' | 'HTI' | 'HUN' | 'IDN' | 'IRL' | 'ISR' | 'IMN' | 'IND' | 'IOT' | 'IRQ' | 'IRN' | 'ISL' | 'ITA' | 'JEY' | 'JAM' | 'JOR' | 'JPN' | 'KEN' | 'KGZ' | 'KHM' | 'KIR' | 'COM' | 'KNA' | 'PRK' | 'KOR' | 'KWT' | 'CYM' | 'KAZ' | 'LAO' | 'LBN' | 'LCA' | 'LIE' | 'LKA' | 'LBR' | 'LSO' | 'LTU' | 'LUX' | 'LVA' | 'LBY' | 'MAR' | 'MCO' | 'MDA' | 'MNE' | 'MAF' | 'MDG' | 'MHL' | 'MKD' | 'MLI' | 'MMR' | 'MNG' | 'MAC' | 'MNP' | 'MTQ' | 'MRT' | 'MSR' | 'MLT' | 'MUS' | 'MDV' | 'MWI' | 'MEX' | 'MYS' | 'MOZ' | 'NAM' | 'NCL' | 'NER' | 'NFK' | 'NGA' | 'NIC' | 'NLD' | 'NOR' | 'NPL' | 'NRU' | 'NIU' | 'NZL' | 'OMN' | 'PAN' | 'PER' | 'PYF' | 'PNG' | 'PHL' | 'PAK' | 'POL' | 'SPM' | 'PCN' | 'PRI' | 'PSE' | 'PRT' | 'PLW' | 'PRY' | 'QAT' | 'REU' | 'ROU' | 'SRB' | 'RUS' | 'RWA' | 'SAU' | 'SLB' | 'SYC' | 'SDN' | 'SWE' | 'SGP' | 'SHN' | 'SVN' | 'SJM' | 'SVK' | 'SLE' | 'SMR' | 'SEN' | 'SOM' | 'SUR' | 'SSD' | 'STP' | 'SLV' | 'SXM' | 'SYR' | 'SWZ' | 'TCA' | 'TCD' | 'TGO' | 'THA' | 'TJK' | 'TKL' | 'TLS' | 'TKM' | 'TUN' | 'TON' | 'TUR' | 'TTO' | 'TUV' | 'TWN' | 'TZA' | 'UKR' | 'UGA' | 'USA' | 'URY' | 'UZB' | 'VAT' | 'VCT' | 'VEN' | 'VGB' | 'VIR' | 'VNM' | 'VUT' | 'WLF' | 'WSM' | 'XKX' | 'YEM' | 'MYT' | 'ZAF' | 'ZMB' | 'ZWE' required

ISO 3166-1 alpha-3 country codes.

account_numberstring required
institution_idstring required
institution_namestring required

Full legal name of the bank institution.

institution_clearing_codestring required

Additional local or regional routing codes required by specific payment networks or countries. Examples: Sort codes (UK), BSB numbers (Australia), transit numbers (Canada).

reference_codestring required

Reference code for wire transfers (optional). A unique identifier that should be included in wire transfer memos to help identify and reconcile incoming payments.

created_atstring required
modified_atstring required

Example response

{
  "external_account_id": "381b013e-8893-11f0-b308-2eaa4f6974f2",
  "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
  "network": "ETHEREUM",
  "nickname": "Primary Operating Account",
  "account_holder_name": "TechStart Holdings LLC",
  "currency": "USDC",
  "account_number": "4447891623",
  "institution_id": "CHASUS33",
  "institution_name": "JPMorgan Chase Bank, N.A.",
  "institution_clearing_code": "021000021",
  "intermediary_bank": {
    "institution_id": "PNBPUS3NNYC"
  },
  "reference_code": "36AC1ECAF659",
  "created_at": "2025-08-21T07:56:57.981Z",
  "modified_at": "2025-08-21T07:56:57.981Z",
  "recipient": {
    "recipient_id": "4728c2b9-6df7-11f0-b1f6-6a7838eca3f8",
    "customer_id": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
    "business_type": "INDIVIDUAL",
    "full_name": "John Doe",
    "nickname": "John's Business",
    "email": "john.doe@example.com",
    "relationship": "VENDOR",
    "status": "active",
    "address": {
      "full_address": "490 2nd St Suite 300, San Francisco, CA 94107",
      "country_code": "USA",
      "address_line1": "490 2nd St",
      "address_line2": "Suite 300",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94107"
    },
    "created_at": "2025-10-29T02:46:25.096305Z",
    "modified_at": "2025-10-29T02:46:25.096305Z"
  }
}