Skip to main content
PUT
/
v1
/
beneficiaries
/
{id}
curl -X PUT "https://api.zuba.com/v1/beneficiaries/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "middleName": "Michael",
    "email": "john.smith@example.com",
    "address": "456 Oak Ave",
    "addressLine2": "Suite 100",
    "city": "Boston",
    "postcode": "02101",
    "status": "active"
  }'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "individual",
  "name": "John Smith",
  "middleName": "Michael",
  "email": "john.smith@example.com",
  "country": "US",
  "address": "456 Oak Ave",
  "addressLine2": "Suite 100",
  "city": "Boston",
  "postcode": "02101",
  "accounts": [
    {
      "id": "account-123e4567-e89b-12d3-a456-426614174000",
      "type": "iban",
      "currency": "EUR",
      "data": {
        "iban": "DE89370400440532013000",
        "bic": "DEUTDEFF"
      },
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T15:45:00Z"
}
Update the details of an existing beneficiary. You can modify the name, email address, and status. Note that account information cannot be updated through this endpoint - accounts must be managed separately. 
curl -X PUT "https://api.zuba.com/v1/beneficiaries/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "middleName": "Michael",
    "email": "john.smith@example.com",
    "address": "456 Oak Ave",
    "addressLine2": "Suite 100",
    "city": "Boston",
    "postcode": "02101",
    "status": "active"
  }'

​
Path Parameters

​
id
string
required
Unique identifier for the beneficiary (UUID format)

​
Request Body

All fields are optional - only include the fields you want to update.
​
name
string
Full name of the beneficiary
​
middleName
string
Middle name of the beneficiary (max 100 characters). Set to null to clear.
​
email
string
Email address of the beneficiary. Must be a valid email format.
​
address
string
Address line 1 of the beneficiary (max 200 characters)
​
addressLine2
string
Address line 2 of the beneficiary (max 200 characters). Set to null to clear.
​
city
string
City of the beneficiary (max 100 characters)
​
postcode
string
Postal code of the beneficiary (max 20 characters)
​
notes
string
Notes about the beneficiary (max 500 characters)
​
type
enum
Beneficiary type
​
status
enum
Status of the beneficiary
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "individual",
  "name": "John Smith",
  "middleName": "Michael",
  "email": "john.smith@example.com",
  "country": "US",
  "address": "456 Oak Ave",
  "addressLine2": "Suite 100",
  "city": "Boston",
  "postcode": "02101",
  "accounts": [
    {
      "id": "account-123e4567-e89b-12d3-a456-426614174000",
      "type": "iban",
      "currency": "EUR",
      "data": {
        "iban": "DE89370400440532013000",
        "bic": "DEUTDEFF"
      },
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-16T15:45:00Z"
}

​
Response Fields

The response returns the complete updated beneficiary object with the same structure as the Get Beneficiary endpoint.
​
id
string
Unique identifier for the beneficiary (unchanged)
​
type
string
Beneficiary type: individual or business
​
name
string
Updated name of the beneficiary
​
middleName
string
Middle name of the beneficiary
​
email
string
Updated email address of the beneficiary
​
country
string
Country code (ISO 3166-1 alpha-2)
​
address
string
Address line 1 of the beneficiary
​
addressLine2
string
Address line 2 of the beneficiary
​
city
string
City of the beneficiary
​
postcode
string
Postal code of the beneficiary
​
notes
string
Notes about the beneficiary
​
accounts
array
Array of payment accounts (unchanged by this operation)
​
status
string
Updated beneficiary status
​
createdAt
string
Original creation timestamp (unchanged)
​
updatedAt
string
Timestamp when the beneficiary was last updated (reflects this update)

​
Important Notes

Account Management: This endpoint only updates beneficiary-level information. To manage payment accounts (add, remove, or update account details), use the dedicated account management endpoints.
Status Changes: Setting a beneficiary status to suspended will prevent any new payouts from being created for this beneficiary. Existing pending payouts may still be processed.

​
Use Cases

This endpoint is commonly used for:
  • Contact Updates: Updating beneficiary name or email address
  • Status Management: Suspending or reactivating beneficiaries
  • Data Maintenance: Correcting beneficiary information
  • Compliance: Updating beneficiary status based on compliance requirements