Skip to main content
POST
Add a party to an account
Requires scope: manage:accounts — see Required scopes. Associates a party with the account in a role. A party can hold only one role per account.

Authorizations

Headers

x-tenant-id
string<uuid>

Which tenant the request is scoped to, among those your token grants. Omit it when the token grants exactly one tenant; it is required when the token grants more than one. A supplied value must exactly match a tenant the token grants.

Absent when required, blank, malformed, or naming a tenant the token does not grant — each gets the same generic 403 forbidden, which reveals neither whether a tenant exists nor which ones you may use. Send the header once: a repeated header is rejected the same way.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Path Parameters

accountId
string<uuid>
required

Unique account identifier

Body

application/json
partyId
string<uuid>
required

ID of the party to add to the account

roleType
enum<string>
required

Role type for the party-account relationship.

  • ACCOUNT_HOLDER — the party holds the account
  • PAYOUT_RECIPIENT — the party is an allowed pay-out destination for the account. Required (with cleared KYC/KYB) before a payout route can be created for its bank account. A party may hold this alongside ACCOUNT_HOLDER on the same account, which is the self-payout case.
Available options:
ACCOUNT_HOLDER,
PAYOUT_RECIPIENT

Response

Party role added

success
boolean

Indicates whether the request was successful

result
object

Represents the relationship between a Party and an Account