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",
"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": "jsmith@example.com",
"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": "jsmith@example.com",
"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"
}
]
}{
"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), validated at the Kong edge.
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 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
⌘I
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",
"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": "jsmith@example.com",
"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": "jsmith@example.com",
"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"
}
]
}{
"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>"
}
]
}