External Accounts

Add a new platform external account

Changed on

Register a new external bank account for the platform.

post/platform/external-accounts

Request

  • Base URL: https://api.lightspark.com/grid/2025-10-13
  • URL: https://api.lightspark.com/grid/2025-10-13/platform/external-accounts
  • Auth: HTTP basic

Request body

currencystring required

The ISO 4217 currency code

platformAccountIdstring

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

ownershipType'FIRST_PARTY' | 'THIRD_PARTY'

Whether the external account belongs to the customer themselves (FIRST_PARTY) or to someone else (THIRD_PARTY). Required when creating self-custody crypto wallet external accounts on platforms subject to counterparty requirements — for example, under the EU Travel Rule or similar requirements in other regions; recommended for all other accounts, where providing it can unlock additional capabilities and smoother compliance handling.

Example request

{
  "currency": "USD",
  "platformAccountId": "ext_acc_123456",
  "ownershipType": "FIRST_PARTY",
  "accountInfo": {
    "accountType": "AED_ACCOUNT",
    "iban": "AE070331234567890123456",
    "swiftCode": "EBILAEAD"
  }
}

Response

External account created successfully

idstring required

The system generated identifier of this account

customerIdstring

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

status'PENDING' | 'ACTIVE' | 'PENDING_OWNERSHIP_VERIFICATION' | 'UNVERIFIED' | 'UNDER_REVIEW' | 'INACTIVE' required

Status of an external account.

PENDING_OWNERSHIP_VERIFICATION: the wallet's ownership must be verified (e.g. under the EU Travel Rule) before unrestricted use; transfers below regulatory thresholds are still allowed. UNVERIFIED: the most recent verification attempt failed; start a new challenge to retry. Successful verification moves the account to ACTIVE.

platformAccountIdstring

Optional platform-specific identifier for this account

ownershipType'FIRST_PARTY' | 'THIRD_PARTY'

Whether the external account belongs to the customer themselves (FIRST_PARTY) or to someone else (THIRD_PARTY). Required when creating self-custody crypto wallet external accounts on platforms subject to counterparty requirements — for example, under the EU Travel Rule or similar requirements in other regions; recommended for all other accounts, where providing it can unlock additional capabilities and smoother compliance handling.

currencystring required

The ISO 4217 currency code

defaultUmaDepositAccountboolean

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.

beneficiaryVerificationStatus'MATCHED' | 'PARTIAL_MATCH' | 'NOT_MATCHED' | 'UNSUPPORTED' | 'CHECKED_BY_RECEIVING_FI' | 'PENDING'

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

StatusDescription
MATCHEDThe beneficiary name is an exact match
PARTIAL_MATCHThe beneficiary name is a fuzzy match
NOT_MATCHEDThe beneficiary name does not match
UNSUPPORTEDThe payment rail does not support name verification
CHECKED_BY_RECEIVING_FIVerification is deferred to the receiving financial institution (e.g. ACH)
PENDINGVerification is still in progress

Example response

{
  "id": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "customerId": "Customer:da459a29-1fb7-41ce-a4cb-eb3a3c9fd7a7",
  "platformAccountId": "acc_123456789",
  "ownershipType": "FIRST_PARTY",
  "currency": "USD",
  "beneficiaryVerifiedData": {
    "fullName": "John Doe"
  },
  "accountInfo": {
    "accountType": "AED_ACCOUNT",
    "iban": "AE070331234567890123456",
    "swiftCode": "EBILAEAD"
  }
}

Changes

  • 556180e5b2aeRevision changes
    • warning

      added the new ACH_SAME_DAY enum value to the ///////// response property for the response status

  • 5b4d838613abRevision changes
    • breaking

      added the new required request property ///

    • warning

      removed the request property //////

    • warning

      removed the optional property /////////// from the response with the status

    • info

      added the optional property //////// to the response with the status