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 --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": "jane@acme.example"
}
}
'{
"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": "jsmith@example.com",
"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": "jsmith@example.com",
"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"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}Authorizations
Access token issued by POST /v1/auth/token.
Application secret (the apiKey issued at registration), required on every request.
Path Parameters
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.
Response
Updated beneficiary.
Available options:
Individual, Business 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 Applies while Unverified.
Available options:
TIER_0, TIER_1 Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Update a beneficiary
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": "jane@acme.example"
}
}
'{
"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": "jsmith@example.com",
"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": "jsmith@example.com",
"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"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}{
"type": "https://errors.zeam.app/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'amount' field must be a positive decimal.",
"instance": "/v1/quotes",
"requestId": "01J8Z6K3QW9F2",
"errors": [
{
"field": "<string>",
"message": "<string>"
}
]
}