Skip to navigation
ExchangeExchangeBeneficiaries

Create beneficiary

Beneficiary created with status: pending. Transitions to active after async compliance validation. Poll until active before use.

Idempotency: Idempotency-Key header recommended (UUIDv4, persisted before the request, reused on retries). Omitting it is permitted — the caller accepts all retry and duplicate risk.

Authentication

AuthorizationBearer
Token obtained via the login flow.

Headers

Idempotency-KeystringOptionalformat: "uuid"

Optional client-generated UUIDv4. Persist before issuing the request and reuse on retries. Omitting it is permitted — the caller accepts all retry and duplicate risk.

Request

This endpoint expects an object.
namestringRequired<=140 characters

Legal name. ≤ 140 chars.

entityTypeenumRequired
Allowed values:
addressobjectRequired
currencystringRequired
ISO 4217.
accountDetailslist of objectsRequired
routingDetailslist of objectsRequired
wireDetailsobjectOptional

Extra bank details required for USD wire payouts. Provide this when a routing detail uses paymentType international_wire or domestic_wire.

domestic_wire (within the US) requires abaRoutingNumber and bankName. international_wire (cross-border) additionally requires bic and bankAddress.

Response

Beneficiary created with status: pending. Transitions to active after async compliance validation. Poll until active before use.

beneficiaryIdstring
statusenum

Poll until active before referencing in a withdrawal.

Allowed values:
currencystring
One currency per beneficiary.
namestring
Legal name.
entityTypeenum
Allowed values:
accountDetailslist of objects
routingDetailslist of objects
createdAtdatetime
statusReasonenum or nullOptional
Allowed values:
addressobjectOptional
activatedAtdatetime or nullOptional

Errors

400
Bad Request Error
401
Unauthorized Error