Replace the worker's entire nominated beneficiary set

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.getpenfold.dev/mcp

Standard setup for AI tools providing an mcp.json file

{
  "Penfold Partner API MCP server": {
    "url": "https://docs.getpenfold.dev/mcp"
  }
}

PUT /employers/{employer_id}/employees/{employee_id}/beneficiaries

O auth2 client credentials

Replace the worker's entire nominated beneficiary set. Existing beneficiaries are deleted and the request body is written as the new set.

Every request must include the full desired beneficiary list. Send every beneficiary you want on record after the write, each with a complete address. Omitting a beneficiary that exists today removes them. There is no partial update or merge-by-id behaviour.

percentage values across all beneficiaries in the request must sum to exactly 100, or the request fails with 400.

Path parameters

employer_id string Required
employee_id string Required

application/json

Body Required

first_name string Required
last_name string Required
phone string | null
relationship string Required

Values are Other, Wife, Husband, Partner, Son, Daughter, Mother, Father, or Sibling.
percentage integer Required

Minimum value is 1, maximum value is 100.
address object Required
Hide address attributes Show address attributes object
- street_number string | null
- line1 string Required
- line2 string | null
- town string | null
- county string | null
- postcode string Required
- country string Required

Responses

200 application/json

Beneficiaries replaced successfully.
Hide response attributes Show response attributes object
- id string Required
- first_name string Required
- last_name string Required
- phone string | null
- relationship string Required
  
  Values are Other, Wife, Husband, Partner, Son, Daughter, Mother, Father, or Sibling.
- percentage integer Required
  
  Share of benefits as a whole-number percentage (all beneficiaries must sum to 100).
  
  Minimum value is 1, maximum value is 100.
- address object Required
  
  Hide address attributes Show address attributes object
  
  street_number string | null
  
  line1 string Required
  
  line2 string | null
  
  town string | null
  
  county string | null
  
  postcode string Required
  
  country string Required
- created_at string(date-time) Required
- updated_at string(date-time) Required
400 application/json

Validation failed (e.g. percentages do not sum to 100).
Hide response attributes Show response attributes object
- error string
  
  A descriptive error message.
- validation_errors array[object]
  
  Hide validation_errors attributes Show validation_errors attributes object
  
  field string Required
  
  The name of the field that failed validation.
  
  message string Required
  
  A descriptive error message.
401 application/json

Unauthorized.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
404 application/json

Employee or employer not found.
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
405 application/json

Method not allowed
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.

PUT /employers/{employer_id}/employees/{employee_id}/beneficiaries

curl \
 --request PUT 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/employees/{employee_id}/beneficiaries' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '[{"first_name":"string","last_name":"string","phone":"string","relationship":"Other","percentage":42,"address":{"street_number":"string","line1":"string","line2":"string","town":"string","county":"string","postcode":"string","country":"string"}}]'

Request examples

[
  {
    "first_name": "string",
    "last_name": "string",
    "phone": "string",
    "relationship": "Other",
    "percentage": 42,
    "address": {
      "street_number": "string",
      "line1": "string",
      "line2": "string",
      "town": "string",
      "county": "string",
      "postcode": "string",
      "country": "string"
    }
  }
]

Response examples (200)

[
  {
    "id": "string",
    "first_name": "string",
    "last_name": "string",
    "phone": "string",
    "relationship": "Other",
    "percentage": 42,
    "address": {
      "street_number": "string",
      "line1": "string",
      "line2": "string",
      "town": "string",
      "county": "string",
      "postcode": "string",
      "country": "string"
    },
    "created_at": "2026-05-04T09:42:00Z",
    "updated_at": "2026-05-04T09:42:00Z"
  }
]

Response examples (400)

{
  "error": "Bad request: invalid data provided.",
  "validation_errors": [
    {
      "field": "email",
      "message": "Email address is invalid."
    }
  ]
}

Response examples (401)

{
  "error": "Bad request: invalid data provided."
}

Response examples (404)

{
  "error": "Bad request: invalid data provided."
}

Response examples (405)

{
  "error": "Bad request: invalid data provided."
}