Sign in

v5

latestOpenAPI 3.1.0Proprietary2026-08-011476181.4 MB
Agent Operations

Add an external account

Register a new external bank account or wallet for the authenticated agent's customer. Requires the MANAGE_EXTERNAL_ACCOUNTS permission in the agent's policy. The customerId field is optional and will be inferred from the agent's associated customer if omitted.

post/agents/me/external-accounts

Request body

customerIdstring

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.

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.

defaultUmaDepositAccountboolean

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.

Example request

{
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "currency": "USD",
  "platformAccountId": "ext_acc_123456",
  "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' | 'UNDER_REVIEW' | 'INACTIVE' required

Status of an external account

platformAccountIdstring

Optional platform-specific identifier for this account

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",
  "currency": "USD",
  "beneficiaryVerifiedData": {
    "fullName": "John Doe"
  },
  "accountInfo": {
    "accountType": "AED_ACCOUNT",
    "iban": "AE070331234567890123456",
    "swiftCode": "EBILAEAD"
  }
}