Add a beneficiary

Adds a beneficiary under the association resolved from the token. Required-field enforcement is handled by the upstream service, not the gateway. Payment destinations are managed separately via the /payment-destinations sub-resource.

This creates a real, permanently persisted third-party record even when called with sandbox credentials. Sandbox only simulates off-ramp payout execution; it does not sandbox record creation.

POST /beneficiaries

Add a beneficiary

cURL

curl --request POST \
  --url https://api.zeam.money/gw/v1/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "beneficiaryType": "Business",
  "reference": "ACME-001",
  "business": {
    "companyName": "Acme Ltd",
    "registrationNumber": "2020/123456/07",
    "countryOfRegistrationIsoCode2": "ZA"
  }
}
'

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "beneficiaryType": "Individual",
  "reference": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "individual": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "firstName": "<string>",
    "lastName": "<string>",
    "idNumber": "<string>",
    "dateOfBirth": "2023-12-25",
    "nationality": "<string>",
    "mobileNumber": "<string>",
    "email": "[e-mail]",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "business": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "companyName": "<string>",
    "registrationNumber": "<string>",
    "countryOfRegistration": "<string>",
    "taxId": "<string>",
    "industry": "<string>",
    "contactPersonName": "<string>",
    "contactNumber": "<string>",
    "contactEmail": "[e-mail]",
    "registeredAddress": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "paymentDestinations": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "method": "BANK",
      "beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "label": "<string>",
      "isPrimary": true,
      "countryIsoCode2": "<string>",
      "currencyIsoCode3": "<string>",
      "bankName": "<string>",
      "bankCode": "<string>",
      "accountNumber": "<string>",
      "accountName": "<string>",
      "accountType": "<string>",
      "sortCode": "<string>",
      "iban": "<string>",
      "swiftBic": "<string>",
      "branchCode": "<string>",
      "mobileNumber": "<string>",
      "mobileProvider": "<string>",
      "networkName": "<string>",
      "assetSymbol": "<string>",
      "walletAddress": "<string>",
      "isZeamAccount": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "addresses": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "addressType": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "stateProvince": "<string>",
      "postalCode": "<string>",
      "countryCode": "<string>",
      "isPrimary": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "tags": [
    {
      "tag": "<string>",
      "createdAt": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization · string · header · required

Access token issued by POST /v1/auth/token.

x-zeam-auth · string · header · required

Application secret (the apiKey issued at registration), required on every request.

Body

application/json

Used for both POST (create) and PATCH (update) beneficiary requests. For PATCH, only fields present in the body are changed. beneficiaryType is always required — echo it from a prior Get even when not changing it. Payment destinations are managed separately via the /payment-destinations sub-resource.

beneficiaryType · enum<string> · required

Available options: Individual, Business

reference · string

individual · object

Show child attributes

business · object

Show child attributes

addresses · object[]

Show child attributes

tags · string[]

Response

201

application/json

Beneficiary created.

id · string<uuid> · required

beneficiaryType · enum<string> · required

Available options: Individual, Business

reference · string

createdAt · string<date-time>

updatedAt · string<date-time>

individual · object

Show child attributes

business · object

Show child attributes

paymentDestinations · object[]

Show child attributes

addresses · object[]

Show child attributes

tags · object[]

Show child attributes