Penfold Partner API

Update an employee's information

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
PATCH /employers/{employer_id}/employees/{employee_id}
O auth2 client credentials

Update an employee's information. All fields are optional — only provided fields are updated; at least one field must be supplied. Once marked as a leaver (exit_date), the employee record will no longer be accessible under the employer.

Path parameters

  • employer_id string Required
  • employee_id string Required
application/json

Body Required

Employee update data.

  • email string(email)

    Email address of the employee.

  • forename string

    The employee's first name.

  • surname string

    The employee's last name.

  • title string

    The employee's title, e.g. Mr., Mrs., Dr., etc.

  • date_of_birth string(date)

    The employee's date of birth, in YYYY-MM-DD format.

  • address_line1 string

    The first line of the employee's address.

  • postcode string

    The postal code of the employee's address.

  • national_insurance_number string(national_insurance_number)

    The employee's National Insurance number.

  • employment_start_date string(date)

    The date the employee started their employment, in YYYY-MM-DD format.

  • exit_date string(date)

    The date the employee's employment ended, in YYYY-MM-DD format. Provide only when marking the employee as a leaver. Emits an Employment webhook with action Ended and initiated_by Partner.

Responses

  • 204

    Successfully updated the employee's information

  • 400 application/json

    Bad request, the request is malformed or contains invalid data.

    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, the request requires authentication, and the provided credentials are either missing or incorrect.

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 404 application/json

    Employee or employer not found, the specified employee_id or employer_id does not match any existing records.

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
PATCH /employers/{employer_id}/employees/{employee_id} 
curl \
 --request PATCH 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/employees/{employee_id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"exit_date":"2023-03-22"}'
Request example 
{
  "exit_date": "2023-03-22"
}
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."
}