Skip to main content
PATCH
cURL

Headers

Authorization
string
required

Bearer token. Format: Bearer <api_key>

Idempotency-Key
string

Unique key per logical operation. UUID v4 recommended. Max 255 characters.

Path Parameters

beneficiaryId
string
required

Body

application/json

Request body for updating a beneficiary. Fields set to null are cleared.

accountId
string
required

Account this beneficiary belongs to.

nickname
string

Updated display name.

walletAddress
string

Updated wallet address (crypto beneficiaries only).

entityType
enum<string>

Entity type.

Available options:
INDIVIDUAL,
BUSINESS
email
string | null

Email address. Set to null to clear.

phoneNumber
string | null

Phone number. Set to null to clear.

firstName
string | null

First name.

lastName
string | null

Last name.

Legal name.

dateOfBirth
string | null

Date of birth (YYYY-MM-DD).

businessName
string | null

Business name.

registrationNumber
string | null

Registration / incorporation number.

addressLine1
string | null

Address line 1.

addressLine2
string | null

Address line 2.

city
string | null

City.

region
string | null

Region / state / province.

zipCode
string | null

ZIP / postal code.

country
string | null

Country code (ISO 3166-1 alpha-2).

taxId
string | null

Tax ID.

taxIdType
string | null

Tax ID type (e.g., SSN, TIN).

tags
string[]

Free-form tags (max 20 tags, each up to 100 characters).

metadata
object

Arbitrary metadata (max 50 keys, max 4 KB serialized).

Response

The request has succeeded.

A beneficiary (recipient) registered for payouts from an account. All responses share this shape — the type field indicates which detail object (crypto or bank) is populated; the other will be null. Shared identity fields may be null in list and create responses.

object
enum<string>
required

Object type. Always beneficiary.

Available options:
beneficiary
beneficiaryId
string
required

Unique beneficiary identifier.

accountId
string
required

Account this beneficiary belongs to.

type
enum<string>
required

Beneficiary type.

Available options:
CRYPTO,
BANK,
NXOSNET
nickname
string
required

Display name for the beneficiary.

status
enum<string>
required

Current status.

Available options:
ACTIVE,
INACTIVE,
BLOCKED,
ARCHIVED
entityType
enum<string> | null
required

Entity type.

Available options:
INDIVIDUAL,
BUSINESS
email
string | null
required

Email address.

phoneNumber
string | null
required

Phone number.

firstName
string | null
required

First name (individuals).

lastName
string | null
required

Last name (individuals).

businessName
string | null
required

Business name (businesses).

country
string | null
required

Country code (ISO 3166-1 alpha-2).

addressLine1
string | null
required

Address line 1.

addressLine2
string | null
required

Address line 2.

city
string | null
required

City.

region
string | null
required

Region / state / province.

zipCode
string | null
required

ZIP / postal code.

crypto
object | null
required

Crypto-specific details. Present when type is CRYPTO, otherwise null.

bank
object | null
required

Bank-specific details. Present when type is BANK, otherwise null.

nxosnet
object | null
required

Internal NXOS→NXOS details. Present when type is NXOSNET, otherwise null.

createdAt
string
required

When the beneficiary was created.