Penfold Partner API

Mark multiple employees as leavers in a single request

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
POST /employers/{employer_id}/leavers
O auth2 client credentials

Mark multiple employees as leavers in a single request. Idempotent per employee: if employment has already ended, that employee appears in failed rather than causing a 4xx on the whole request.

Emits an Employment webhook with action Ended and initiated_by Partner for each succeeded id. At most 100 entries per request. Each employee_id must appear at most once in the request body.

Unexpected per-employee processing errors also appear in failed; retry those ids idempotently or verify employee status via GET.

Path parameters

  • employer_id string Required
application/json

Body Required

  • employee_id string Required

    Employee to mark as a leaver.

  • exit_date string(date) Required

    Employment end date for this employee (YYYY-MM-DD).

Responses

  • 200 application/json

    Batch leaver request processed.

    Hide response attributes Show response attributes object
    • succeeded array[string] Required

      Employee ids successfully marked as leavers.

    • failed array[object] Required

      Employees that could not be processed. The overall request still returns 200.

      Hide failed attributes Show failed attributes object
      • employee_id string Required

        Employee id that could not be processed.

      • error string Required

        Reason the employee could not be marked as a leaver.
  • 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

    Employer not found, the specified employer_id does not match any existing employer.

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
POST /employers/{employer_id}/leavers 
curl \
 --request POST 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}/leavers' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '[{"employee_id":"string","exit_date":"2026-06-30"}]'
Request examples 
[
  {
    "employee_id": "string",
    "exit_date": "2026-06-30"
  }
]
Response examples (200) 
{
  "succeeded": [
    "string"
  ],
  "failed": [
    {
      "employee_id": "string",
      "error": "string"
    }
  ]
}
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."
}