Retrieve a list of employers.

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

GET /employers

O auth2 client credentials

Responses

200 application/json

List of employers retrieved successfully.
Hide response attributes Show response attributes object
- page_number integer
  
  The current page number.
- page_size integer
  
  The number of employers per page.
- total_items integer
  
  The total number of employers available.
- items array[object]
  
  An array of employer objects on the current page.
  
  Hide items attributes Show items attributes object
  
  id string
  
  The unique identifier for the employer.
  
  created_at string(date-time)
  
  The date and time the employer record was created, in ISO 8601 format.
  
  updated_at string(date-time)
  
  The date and time the employer record was last updated, in ISO 8601 format.
  
  name string
  
  The name of the employer.
  
  contribution_basis string
  
  The basis on which the employer makes pension contributions. Informational only — Penfold does not validate submitted contribution amounts against this basis. Integrators must compute final amounts themselves. Possible values:
  
  QualifyingEarnings: contributions calculated on banded earnings (currently £6,240–£50,270).
  
  TotalPay: contributions calculated on all earnings, with no banding.
  
  BasicPay: contributions calculated on basic pay only.
  
  Values are QualifyingEarnings, TotalPay, or BasicPay.
  
  allows_salary_sacrifice boolean
  
  Whether the employer allows for salary sacrifice. Informational only — used to provide a tailored experience to members in the Penfold app. Penfold processes submissions as-is and makes no amendments to contribution amounts; integrators must provide final amounts regardless of salary sacrifice status.
  
  Default value is false.
  
  external_reference string
  
  An external reference for the employer. Should be used as the value in the EmployerId column in file uploads.
  
  company_number string
  
  Companies House registration number.
  
  payment_method string | null
  
  The payment method used by the employer.
  
  Values are BankTransfer or DirectDebit. Default value is DirectDebit.
  
  primary_contact_email string(email) | null
  
  The email address of the primary contact for the employer.
  
  primary_contact_role string | null
  
  Role of the employer primary contact.
  
  Values are CompanyDirector, Finance, or HR.
  
  default_employee_contributions_percent number | null
  
  Default employee contribution percentage.
  
  Minimum value is 0, maximum value is 100.
  
  default_employer_contributions_percent number | null
  
  Default employer contribution percentage.
  
  Minimum value is 0, maximum value is 100.
  
  status
  
  The status of the employer.
  
  Values are PendingPa, PaSent, Signed, PendingAml, or Active. Default value is PendingPa.
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.

GET /employers

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

Response examples (200)

{
  "page_number": 1,
  "page_size": 10,
  "total_items": 100,
  "items": [
    {
      "id": "e1234-abcd-5678-efgh",
      "created_at": "2023-03-01T12:00:00Z",
      "updated_at": "2023-03-15T12:00:00Z",
      "name": "Acme Corp.",
      "contribution_basis": "QualifyingEarnings",
      "allows_salary_sacrifice": false,
      "external_reference": "ABC123",
      "company_number": "12345678",
      "payment_method": "DirectDebit",
      "primary_contact_email": "john.doe@example.com",
      "primary_contact_role": "HR",
      "default_employee_contributions_percent": 5,
      "default_employer_contributions_percent": 3,
      "status": "Active"
    }
  ]
}

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