Penfold Partner API

List the worker's nominated beneficiaries

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

mcp.json 
{
  "Penfold Partner API MCP server": {
    "url": "https://docs.getpenfold.dev/mcp"
  }
}
Close
GET /employers/{employer_id}/employees/{employee_id}/beneficiaries
O auth2 client credentials

List the worker's nominated beneficiaries.

Path parameters

  • employer_id string Required
  • employee_id string Required

Responses

  • 200 application/json

    Beneficiaries retrieved 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
  • 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.
GET /employers/{employer_id}/employees/{employee_id}/beneficiaries 
curl \
 --request GET 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/employees/{employee_id}/beneficiaries' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
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 (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."
}