---
title: "Add a new platform external account"
method: POST
path: "/platform/external-accounts"
tags: ["External Accounts"]
---

# Add a new platform external account

`POST /platform/external-accounts`

Register a new external bank account for the platform.

**Sandbox Testing:** In sandbox mode, use these account number patterns to test different transfer scenarios. These patterns should be used with the primary alias, address, or identifier of whatever account type you're testing. For example, the US account number, a CLABE, an IBAN, a spark wallet address, etc. The failure patterns are:
- Account numbers ending in **002**: Insufficient funds (transfer-in will fail)
- Account numbers ending in **003**: Account closed/invalid (transfers will fail)
- Account numbers ending in **004**: Transfer rejected (bank rejects the transfer)
- Account numbers ending in **005**: Timeout/delayed failure (stays pending ~30s, then fails)
- Any other account number: Success (transfers complete normally)

## Request body

- ExternalAccountCreateRequest
  - `customerId` string — The ID of the customer for whom to create the external account. If not provided, the external account will be created on behalf of the platform.
  - `currency` string, required — The ISO 4217 currency code
  - `platformAccountId` string — Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier.
  - `defaultUmaDepositAccount` boolean — Whether to set the external account as the default UMA deposit account. When set to true, incoming payments to this customer's UMA address will be automatically deposited into this external account. False if not provided. Note that only one external account can be set as the default UMA deposit account for a customer, so if there is already a default UMA deposit account, this will override the existing default UMA deposit account. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer.
  - `accountInfo` union, required
    - UsAccountExternalAccountInfo
      - `accountType` 'US_ACCOUNT', required — Type of external account or wallet
      - `accountNumber` string, required — US bank account number
      - `routingNumber` string, required — ACH routing number (9 digits)
      - `accountCategory` 'CHECKING' | 'SAVINGS', required — Type of account (checking or savings)
      - `bankName` string — Name of the bank
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - ClabeAccountExternalAccountInfo
      - `accountType` 'CLABE', required — Type of external account or wallet
      - `clabeNumber` string, required — 18-digit CLABE number (Mexican banking standard)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - PixAccountExternalAccountInfo
      - `accountType` 'PIX', required — Type of external account or wallet
      - `pixKey` string, required — PIX key for Brazilian instant payments
      - `pixKeyType` 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'RANDOM', required — Type of PIX key being used
      - `taxId` string, required — Tax ID of the account holder
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - IbanAccountExternalAccountInfo
      - `accountType` 'IBAN', required — Type of external account or wallet
      - `iban` string, required — International Bank Account Number
      - `swiftBic` string, required — SWIFT/BIC code (8 or 11 characters)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - UpiAccountExternalAccountInfo
      - `accountType` 'UPI', required — Type of external account or wallet
      - `vpa` string, required — Virtual Payment Address for UPI payments
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - NgnAccountExternalAccountInfo
      - `accountType` 'NGN_ACCOUNT', required — Type of external account or wallet
      - `accountNumber` string, required — Nigerian bank account number
      - `bankName` string, required — Name of the bank
      - `purposeOfPayment` 'GIFT' | 'SELF' | 'GOODS_OR_SERVICES' | 'EDUCATION' | 'HEALTH_OR_MEDICAL' | 'REAL_ESTATE_PURCHASE' | 'LOAN_PAYMENT' | 'TAX_PAYMENT' | 'UTILITY_BILL' | 'DONATION' | 'TRAVEL' | 'OTHER', required — Purpose of payment
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - CadAccountExternalAccountInfo
      - `accountType` 'CAD_ACCOUNT', required — Type of external account or wallet
      - `bankCode` string, required — Canadian financial institution number (3 digits)
      - `branchCode` string, required — Transit number identifying the branch (5 digits)
      - `accountNumber` string, required — Bank account number (7-12 digits)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - GbpAccountExternalAccountInfo
      - `accountType` 'GBP_ACCOUNT', required — Type of external account or wallet
      - `sortCode` string, required — UK bank sort code (6 digits, may include hyphens)
      - `accountNumber` string, required — UK bank account number (8 digits)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - PhpAccountExternalAccountInfo
      - `accountType` 'PHP_ACCOUNT', required — Type of external account or wallet
      - `bankName` string, required — Name of the beneficiary's bank
      - `accountNumber` string, required — Bank account number
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - SgdAccountExternalAccountInfo
      - `accountType` 'SGD_ACCOUNT', required — Type of external account or wallet
      - `bankName` string, required — Name of the beneficiary's bank
      - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters)
      - `accountNumber` string, required — Bank account number
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - SparkWalletExternalAccountInfo
      - `accountType` 'SPARK_WALLET', required — Type of external account or wallet
      - `address` string, required — Spark wallet address
    - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided.
      - `accountType` 'LIGHTNING', required — Type of external account or wallet
      - `invoice` string — 1-time use lightning bolt11 invoice payout destination
      - `bolt12` string — A bolt12 offer which can be reused as a payment destination
      - `lightningAddress` string — A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination.
    - SolanaWalletExternalAccountInfo
      - `accountType` 'SOLANA_WALLET', required — Type of external account or wallet
      - `address` string, required — Solana wallet address
    - TronWalletExternalAccountInfo
      - `accountType` 'TRON_WALLET', required — Type of external account or wallet
      - `address` string, required — Tron wallet address
    - PolygonWalletExternalAccountInfo
      - `accountType` 'POLYGON_WALLET', required — Type of external account or wallet
      - `address` string, required — Polygon eth wallet address
    - BaseWalletExternalAccountInfo
      - `accountType` 'BASE_WALLET', required — Type of external account or wallet
      - `address` string, required — Base eth wallet address

## Response `201`

External account created successfully

- ExternalAccount
  - `id` string, required — The system generated identifier of this account
  - `customerId` string — The customer this account is tied to, or null if the account is on behalf of the platform.
  - `status` 'PENDING' | 'ACTIVE' | 'UNDER_REVIEW' | 'INACTIVE', required — Status of an external account
  - `platformAccountId` string — Optional platform-specific identifier for this account
  - `currency` string, required — The ISO 4217 currency code
  - `defaultUmaDepositAccount` boolean — Whether this account is the default UMA deposit account for the customer. If true, incoming UMA payments to this customer's UMA address will be automatically deposited into this account instead of the primary internal account. False if not provided. Note that at most, one external account can be set as the default UMA deposit account for a customer. If there is no default UMA deposit account, incoming UMA payments will be deposited into the primary internal account for the customer.
  - `accountInfo` union, required
    - UsAccountExternalAccountInfo
      - `accountType` 'US_ACCOUNT', required — Type of external account or wallet
      - `accountNumber` string, required — US bank account number
      - `routingNumber` string, required — ACH routing number (9 digits)
      - `accountCategory` 'CHECKING' | 'SAVINGS', required — Type of account (checking or savings)
      - `bankName` string — Name of the bank
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - ClabeAccountExternalAccountInfo
      - `accountType` 'CLABE', required — Type of external account or wallet
      - `clabeNumber` string, required — 18-digit CLABE number (Mexican banking standard)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - PixAccountExternalAccountInfo
      - `accountType` 'PIX', required — Type of external account or wallet
      - `pixKey` string, required — PIX key for Brazilian instant payments
      - `pixKeyType` 'CPF' | 'CNPJ' | 'EMAIL' | 'PHONE' | 'RANDOM', required — Type of PIX key being used
      - `taxId` string, required — Tax ID of the account holder
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - IbanAccountExternalAccountInfo
      - `accountType` 'IBAN', required — Type of external account or wallet
      - `iban` string, required — International Bank Account Number
      - `swiftBic` string, required — SWIFT/BIC code (8 or 11 characters)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - UpiAccountExternalAccountInfo
      - `accountType` 'UPI', required — Type of external account or wallet
      - `vpa` string, required — Virtual Payment Address for UPI payments
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - NgnAccountExternalAccountInfo
      - `accountType` 'NGN_ACCOUNT', required — Type of external account or wallet
      - `accountNumber` string, required — Nigerian bank account number
      - `bankName` string, required — Name of the bank
      - `purposeOfPayment` 'GIFT' | 'SELF' | 'GOODS_OR_SERVICES' | 'EDUCATION' | 'HEALTH_OR_MEDICAL' | 'REAL_ESTATE_PURCHASE' | 'LOAN_PAYMENT' | 'TAX_PAYMENT' | 'UTILITY_BILL' | 'DONATION' | 'TRAVEL' | 'OTHER', required — Purpose of payment
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - CadAccountExternalAccountInfo
      - `accountType` 'CAD_ACCOUNT', required — Type of external account or wallet
      - `bankCode` string, required — Canadian financial institution number (3 digits)
      - `branchCode` string, required — Transit number identifying the branch (5 digits)
      - `accountNumber` string, required — Bank account number (7-12 digits)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - GbpAccountExternalAccountInfo
      - `accountType` 'GBP_ACCOUNT', required — Type of external account or wallet
      - `sortCode` string, required — UK bank sort code (6 digits, may include hyphens)
      - `accountNumber` string, required — UK bank account number (8 digits)
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - PhpAccountExternalAccountInfo
      - `accountType` 'PHP_ACCOUNT', required — Type of external account or wallet
      - `bankName` string, required — Name of the beneficiary's bank
      - `accountNumber` string, required — Bank account number
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - SgdAccountExternalAccountInfo
      - `accountType` 'SGD_ACCOUNT', required — Type of external account or wallet
      - `bankName` string, required — Name of the beneficiary's bank
      - `swiftCode` string, required — SWIFT/BIC code (8 or 11 characters)
      - `accountNumber` string, required — Bank account number
      - `beneficiary` union, required
        - IndividualBeneficiary
          - `beneficiaryType` 'INDIVIDUAL', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `fullName` string, required — Individual's full name
          - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
          - `nationality` string, required — Country code (ISO 3166-1 alpha-2)
        - BusinessBeneficiary
          - `beneficiaryType` 'BUSINESS', required — Whether the beneficiary is an individual or a business entity
          - `address` Address
            - `line1` string, required — Street address line 1
            - `line2` string — Street address line 2
            - `city` string — City
            - `state` string — State/Province/Region
            - `postalCode` string, required — Postal/ZIP code
            - `country` string, required — Country code (ISO 3166-1 alpha-2)
          - `legalName` string, required — Legal name of the business
          - `registrationNumber` string — Business registration number
          - `taxId` string — Tax identification number
    - SparkWalletExternalAccountInfo
      - `accountType` 'SPARK_WALLET', required — Type of external account or wallet
      - `address` string, required — Spark wallet address
    - LightningExternalAccountInfo — Lightning payment destination. Exactly one of `invoice`, `bolt12`, or `lightningAddress` must be provided.
      - `accountType` 'LIGHTNING', required — Type of external account or wallet
      - `invoice` string — 1-time use lightning bolt11 invoice payout destination
      - `bolt12` string — A bolt12 offer which can be reused as a payment destination
      - `lightningAddress` string — A lightning address which can be used as a payment destination. Note that for UMA addresses, no external account is needed. You can use the UMA address directly as a destination.
    - SolanaWalletExternalAccountInfo
      - `accountType` 'SOLANA_WALLET', required — Type of external account or wallet
      - `address` string, required — Solana wallet address
    - TronWalletExternalAccountInfo
      - `accountType` 'TRON_WALLET', required — Type of external account or wallet
      - `address` string, required — Tron wallet address
    - PolygonWalletExternalAccountInfo
      - `accountType` 'POLYGON_WALLET', required — Type of external account or wallet
      - `address` string, required — Polygon eth wallet address
    - BaseWalletExternalAccountInfo
      - `accountType` 'BASE_WALLET', required — Type of external account or wallet
      - `address` string, required — Base eth wallet address

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `409` — Conflict - External account already exists
- `500` — Internal service error

## Changes

- **2026-02-06** `9d1655bef82d` — 36 breaking, 1 warning, 37 info
  - added `#/components/schemas/LightningInfo` to the `allOf[subschema #1]/accountInfo/oneOf[subschema #12: Lightning]/` request property `allOf` list
  - the response property `allOf[subschema #1]/accountInfo/oneOf[subschema #10: SGD Account]/allOf[#/components/schemas/SgdAccountInfo]/accountType` became optional for the status `201`
  - the response property `allOf[subschema #1]/accountInfo/oneOf[subschema #10: SGD Account]/allOf[subschema #3]/beneficiary/oneOf[subschema #1: Individual Beneficiary]/allOf[subschema #2]/beneficiaryType` became optional for the status `201`
  - the response property `allOf[subschema #1]/accountInfo/oneOf[subschema #10: SGD Account]/allOf[subschema #3]/beneficiary/oneOf[subschema #2: Business Beneficiary]/allOf[subschema #2]/beneficiaryType` became optional for the status `201`
  - …70 more
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/platform/external-accounts/post.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/9d1655bef82d/schema)