Retrieve a single employee

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

GET /employers/{employer_id}/employees/{employee_id}

O auth2 client credentials

Retrieve a single employee (worker) record. Read-only. Returns the same Employee schema as the paginated list endpoint, including member_scheme_status and latest contribution percentages.

Path parameters

employer_id string Required
employee_id string Required

Responses

200 application/json

Employee retrieved 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, in YYYY-MM-DD format.
- address_line1 string Required
  
  The first line of the employee's address.
- postcode string Required
  
  The postal code of the employee's address.
- national_insurance_number string Required
  
  The employee's National Insurance number.
- employment_start_date string(date) Required
  
  The date the employee started their employment, in YYYY-MM-DD format.
- exit_date string(date) Required
  
  The date the employee's employment ended, in YYYY-MM-DD format (if applicable).
- opt_out_date string(date) Required
  
  The date the employee opted out of the pension scheme, in YYYY-MM-DD format (if applicable).
- opt_in_date string(date) 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.
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.

GET /employers/{employer_id}/employees/{employee_id}

curl \
 --request GET 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/employees/{employee_id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN"

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_line1": "123 Main Street",
  "postcode": "AB12 3CD",
  "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 (401)

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

Response examples (404)

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