Create Beneficiary

Beneficiaries are recipient identities — either an individual or a business — owned by a platform end-customer account. Each beneficiary can hold one or more payment destinations (bank accounts), which are returned nested in the beneficiary object as payment_destinations[]. Payment destinations are separate resources: the Platform may add them when creating a beneficiary or later through the Payment Destinations endpoints, depending on its onboarding flow.

Enum	Values
`BeneficiaryType`	`individual`, `business`
`BeneficiaryStatus`	`active`, `disabled`

beneficiary_type, first_name / middle_name / last_name, company_name, status, and verified are immutable after creation — they cannot be changed via PATCH. Use the disable action to change status.

Creates a beneficiary under an account. For individual beneficiaries, first_name and last_name are required; for business beneficiaries, company_name is required. The created beneficiary starts with an empty payment_destinations array — add destinations via the payment-destination endpoints.

Path Parameters

string

required

Id of the parent account (e.g. acct_...).

Request Body

enum

individual | business. Defaults to individual. Immutable after creation.

string | null

Honorific or title. Max 20 characters.

string | null

Max 100 characters. Conditional: required when beneficiary_type is individual. Immutable after creation.

string | null

Max 100 characters. Immutable after creation.

string | null

Max 100 characters. Conditional: required when beneficiary_type is individual. Immutable after creation.

string

required

Display name shown in listings and statements. Max 255 characters.

string | null

Max 255 characters. Conditional: required when beneficiary_type is business. Immutable after creation.

string | null

Max 255 characters; must contain @.

string | null

Max 50 characters.

Address

required

Beneficiary address. All sub-fields are required.

Show child attributes

string

required

Street address.

string

required

Max 100 characters.

string

required

State, province, or region. Max 100 characters.

string

required

Max 20 characters.

string

required

Country code string. Send an ISO 3166-1 alpha-2 value; the shared Address schema does not enforce its length.

PaymentCountry

required

ISO 3166-1 alpha-2 country code; must be on the supported payment-country allowlist.

Response

Returns 200 with the new resource’s id. Use Get Beneficiary to retrieve the full object.

string

Id of the newly created beneficiary (e.g. bene_...).

{
  "beneficiary_type": "business",
  "display_name": "Globex Ltd",
  "company_name": "Globex Limited",
  "email": "ap@globex.example",
  "address": {
    "address_line": "5 King St",
    "city": "London",
    "region": "London",
    "postal_code": "EC2V 8AS",
    "country": "GB"
  },
  "country_code": "GB"
}

{
  "id": "bene_9f2c1d7e8a4bx0y1z2a3b4c5"
}

Getting Started

Integration Flows

Webhooks

Endpoints

Path Parameters

Request Body

Response

​Path Parameters

​Request Body

​Response

Path Parameters

Request Body

Response