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

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

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 object

Full UK address for an employee. When provided on PATCH, all required fields must be present — partial address updates are not supported.
Hide address attributes Show address attributes object
- street_number string | null
  
  House or building number, if applicable.
- line1 string Required
  
  The first line of the employee's address.
- line2 string | null
  
  The second line of the employee's address, if applicable.
- town string | null
  
  Town or city.
- county string | null
  
  County, if applicable.
- postcode string Required
  
  The postal code of the employee's address.
- country string Required
  
  ISO 3166-1 alpha-2 country code. Must be GB.
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, as a UTC calendar date in YYYY-MM-DD format.
exit_date string(date)

The date the employee's employment ended, as a UTC calendar date 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

200 application/json

Employee updated successfully.
Hide response attributes Show response attributes object
- id string
  
  Unique identifier for the employee.
- upload_id string
  
  ID of the file upload from which the employee was created (if applicable).
- employer_id string
  
  Identifier for the employer associated with the employee.
- email string(email) Required
  
  Email address of the employee.
- created_at string(date-time) Required
  
  The date and time the employee record was created, in ISO 8601 format.
- updated_at string(date-time) Required
  
  The date and time the employee record was last updated, in ISO 8601 format.
- forename string Required
  
  The employee's first name.
- surname string Required
  
  The employee's last name.
- title string Required
  
  The employee's title, e.g., Mr., Mrs., Dr., etc.
- date_of_birth string(date) Required
  
  The employee's date of birth, as a UTC calendar date in YYYY-MM-DD format.
- address object Required
  
  Full UK address for an employee. When provided on PATCH, all required fields must be present — partial address updates are not supported.
  
  Hide address attributes Show address attributes object
  
  street_number string | null
  
  House or building number, if applicable.
  
  line1 string Required
  
  The first line of the employee's address.
  
  line2 string | null
  
  The second line of the employee's address, if applicable.
  
  town string | null
  
  Town or city.
  
  county string | null
  
  County, if applicable.
  
  postcode string Required
  
  The postal code of the employee's address.
  
  country string Required
  
  ISO 3166-1 alpha-2 country code. Must be GB.
- national_insurance_number string Required
  
  The employee's National Insurance number.
- employment_start_date string(date) Required
  
  The date the employee started their employment, as a UTC calendar date in YYYY-MM-DD format.
- exit_date string(date) | null Required
  
  The date the employee's employment ended, as a UTC calendar date in YYYY-MM-DD format (if applicable).
- opt_out_date string(date) | null Required
  
  The date the employee opted out of the pension scheme, in YYYY-MM-DD format (if applicable).
- opt_in_date string(date) | null Required
  
  The date the employee opted into the pension scheme, in YYYY-MM-DD format (if applicable).
- opt_out_window_start_date string(date) Required
  
  The date the employee's opt out window begins. This is the same date as they were created and enrolled on the scheme.
- opt_out_window_end_date string(date) Required
  
  The date the employee's opt out window ends.
- member_scheme_status string Required
  
  Current scheme membership status for the worker's employment.
  
  Values are OptedIn, Deceased, LeftEmployment, CeasedActiveMembership, OptedOut, EmployerSchemeClosed, or IrregularContributor.
- employee_contributions_percent number | null
  
  Latest elected employee contribution percentage.
  
  Minimum value is 0, maximum value is 100.
- employer_contributions_percent number | null
  
  Latest employer contribution percentage.
  
  Minimum value is 0, maximum value is 100.
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 '"{\n  \"exit_date\": \"2023-03-22\"\n}"'

Request examples

{
  "exit_date": "2023-03-22"
}

{
  "address": {
    "street_number": "123",
    "line1": "Main Street",
    "line2": null,
    "town": "London",
    "county": null,
    "postcode": "AB12 3CD",
    "country": "GB"
  }
}

Response examples (200)

{
  "id": "e1234-abcd-5678-efgh",
  "upload_id": "string",
  "employer_id": "r9876-wxyz-4321-stuv",
  "email": "john.doe@example.com",
  "created_at": "2023-03-01T12:00:00Z",
  "updated_at": "2023-03-15T12:00:00Z",
  "forename": "John",
  "surname": "Doe",
  "title": "Mr.",
  "date_of_birth": "1990-01-01",
  "address": {
    "street_number": "123",
    "line1": "Main Street",
    "line2": "Flat 2",
    "town": "London",
    "county": "Greater London",
    "postcode": "AB12 3CD",
    "country": "GB"
  },
  "national_insurance_number": "AA123456C",
  "employment_start_date": "2023-01-01",
  "exit_date": "2023-12-31",
  "opt_out_date": "2026-05-04",
  "opt_in_date": "2026-05-04",
  "opt_out_window_start_date": "2023-01-01",
  "opt_out_window_end_date": "2023-01-31",
  "member_scheme_status": "OptedIn",
  "employee_contributions_percent": 5,
  "employer_contributions_percent": 3
}

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."
}