Add a new platform external account

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)

POST /platform/external-accounts

cURL

usBankAccount

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/platform/external-accounts \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "USD",
  "accountInfo": {
    "accountType": "USD_ACCOUNT",
    "paymentRails": [
      "ACH"
    ],
    "accountNumber": "12345678901",
    "routingNumber": "123456789",
    "accountCategory": "CHECKING",
    "bankName": "Chase Bank",
    "platformAccountId": "ext_acc_123456",
    "beneficiary": {
      "beneficiaryType": "INDIVIDUAL",
      "fullName": "John Doe",
      "birthDate": "1990-01-15",
      "nationality": "US",
      "address": {
        "line1": "123 Main Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    }
  }
}
'

201

{
  "id": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "status": "ACTIVE",
  "currency": "USD",
  "accountInfo": {
    "accountType": "GBP_ACCOUNT",
    "paymentRails": [],
    "pixKey": "<string>",
    "pixKeyType": "<string>",
    "taxId": "<string>",
    "beneficiary": {
      "fullName": "<string>",
      "birthDate": "<string>",
      "nationality": "<string>",
      "email": "<string>",
      "phoneNumber": "<string>",
      "registrationNumber": "<string>",
      "countryOfResidence": "<string>",
      "address": {
        "line1": "123 Main Street",
        "postalCode": "94105",
        "country": "US",
        "line2": "Apt 4B",
        "city": "San Francisco",
        "state": "CA"
      }
    }
  },
  "customerId": "Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7",
  "platformAccountId": "acc_123456789",
  "defaultUmaDepositAccount": false,
  "beneficiaryVerifiedData": {
    "fullName": "John Doe"
  },
  "cryptoNetwork": "SOLANA_MAINNET"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Body

application/json

currency · string · required

The ISO 4217 currency code

Example:

"USD"

accountInfo · BRL Account · object · required

BRL Account

CAD Account

DKK Account

EUR Account

GBP Account

HKD Account

IDR Account

INR Account

KES Account

MWK Account

MXN Account

MYR Account

NGN Account

PHP Account

RWF Account

SGD Account

THB Account

TZS Account

UGX Account

USD Account

VND Account

XOF Account

ZAR Account

ZMW Account

Spark Wallet

Lightning

Solana Wallet

Tron Wallet

Polygon Wallet

Base Wallet

Show child attributes

platformAccountId · string

Your platform's identifier for the account in your system. This can be used to reference the account by your own identifier.

Example:

"ext_acc_123456"

Response

201

application/json

External account created successfully

id · string · required

The system generated identifier of this account

Example:

"ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

status · enum<string> · required

Status of the external account

Available options: PENDING, ACTIVE, UNDER_REVIEW, INACTIVE

Example:

"ACTIVE"

currency · string · required

The ISO 4217 currency code

Example:

"USD"

accountInfo · BRL Account · object · required

BRL Account

CAD Account

DKK Account

EUR Account

GBP Account

HKD Account

IDR Account

INR Account

KES Account

MWK Account

MXN Account

MYR Account

NGN Account

PHP Account

RWF Account

SGD Account

THB Account

TZS Account

UGX Account

USD Account

VND Account

XOF Account

ZAR Account

ZMW Account

Spark Wallet

Lightning

Solana Wallet

Tron Wallet

Polygon Wallet

Base Wallet

Show child attributes

customerId · string

The customer this account is tied to, or null if the account is on behalf of the platform.

Example:

"Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7"

platformAccountId · string

Optional platform-specific identifier for this account

Example:

"acc_123456789"

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.

Example:

false

beneficiaryVerificationStatus · enum<string>

The result of verifying the beneficiary name against the account holder name

Available options: MATCHED, PARTIAL_MATCH, NOT_MATCHED, UNSUPPORTED, CHECKED_BY_RECEIVING_FI, PENDING

beneficiaryVerifiedData · object

Verified beneficiary data returned by the payment rail, if available

Show child attributes

cryptoNetwork · string

The blockchain network for this external account, if applicable. Present when the account is a cryptocurrency wallet. Example values: SOLANA_MAINNET, ETHEREUM_MAINNET, POLYGON_MAINNET, TRON_MAINNET.

Example:

"SOLANA_MAINNET"