Update a beneficiary

Updates a beneficiary using merge semantics. Only fields present in the body are changed. beneficiaryType must be echoed from a prior Get even when you are not changing it. Payment destinations are not touched by this route — use the payment-destinations sub-resource instead.

PATCH /beneficiaries/{beneficiaryId}

Update a beneficiary

cURL

curl --request PATCH \
  --url https://api.zeam.money/gw/v1/beneficiaries/{beneficiaryId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-zeam-auth: <api-key>' \
  --data '
{
  "beneficiaryType": "Business",
  "business": {
    "contactPersonName": "Jane Smith",
    "contactEmail": "[e-mail]"
  }
}
'

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "beneficiaryType": "Individual",
  "classification": "Unverified",
  "unverifiedTier": "TIER_0",
  "reference": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "individual": {
    "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",
    "updatedBy": "<string>"
  },
  "business": {
    "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",
    "updatedBy": "<string>"
  },
  "paymentDestinations": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "method": "BANK",
      "label": "<string>",
      "isPrimary": true,
      "countryIso": "<string>",
      "countryName": "<string>",
      "currencyCode": "<string>",
      "region": "<string>",
      "bankName": "<string>",
      "bankCode": "<string>",
      "accountNumber": "<string>",
      "accountName": "<string>",
      "accountType": "<string>",
      "sortCode": "<string>",
      "iban": "<string>",
      "swiftBic": "<string>",
      "branchCode": "<string>",
      "mobileNumber": "<string>",
      "networkName": "<string>",
      "assetSymbol": "<string>",
      "walletAddress": "<string>",
      "isZeamAccount": true,
      "verificationStatus": "NOT_REQUIRED",
      "verifyAsMe": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "updatedBy": "<string>"
    }
  ],
  "addresses": [
    {
      "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",
      "updatedBy": "<string>"
    }
  ],
  "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.

Path Parameters

beneficiaryId · string<uuid> · required

Beneficiary identifier.

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

200

application/json

Updated beneficiary.

id · string<uuid> · required

beneficiaryType · enum<string> · required

Available options: Individual, Business

classification · enum<string>

Beneficiary classification. Every beneficiary starts Unverified; approving a payment destination confirms it as Me (the sender's own identity). Read-only; it selects the transaction class a payout is evaluated and limited under.

Available options: Unverified, Me

unverifiedTier · enum<string>

Applies while Unverified.

Available options: TIER_0, TIER_1

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