Penfold Partner API
GET /employers
Bearer auth

Returns all employers belonging to your organisation. Each employer includes both id (UUID) and externalReference (PEN + company number) for cross-referencing.

Responses

  • 200 application/json

    List of employers

    Hide response attribute Show response attribute object
    • employers array[object] Required
      Hide employers attributes Show employers attributes object
      • id string(uuid) Required

        Unique identifier for the employer

      • name string Required

        Employer name

      • externalReference string Required

        Penfold employer reference (PEN + Companies House number)

      • companyNumber string Required

        Companies House number

      • status string Required

        Current status of the employer:

        • AwaitingAgreement: Employer must complete onboarding on Penfold's platform (agreement, AML/KYB)
        • Pending: Onboarding complete, awaiting first payroll submission
        • Active: Fully operational, can process payroll
        • Closed: Employer account closed

        Values are AwaitingAgreement, Pending, Active, or Closed.

      • defaultEmployeeContributionsPercent number Required

        Default employee contribution percentage

      • defaultEmployerContributionsPercent number Required

        Default employer contribution percentage

      • contributionBasis string Required

        Basis on which pension contributions are calculated

        Values are QualifyingEarnings, TotalPay, or BasicPay.

      • allowsSalarySacrifice boolean Required

        Whether the employer allows salary sacrifice

      • paymentMethod string Required

        Payment method for pension contributions

        Value is BankTransfer.

      • createdAt string(date-time) Required

        When the employer was created (ISO 8601)
  • 401 application/json

    Missing or invalid authentication token

    Hide response attribute Show response attribute object
    • error string Required
  • 500 application/json

    Internal server error

    Hide response attribute Show response attribute object
    • error string Required
GET /employers 
curl \
 --request GET 'https://partner-api.getpenfold.com/v1/employers' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "employers": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Ltd",
      "status": "Active",
      "createdAt": "2025-01-15T10:00:00Z",
      "companyNumber": "12345678",
      "paymentMethod": "BankTransfer",
      "contributionBasis": "QualifyingEarnings",
      "externalReference": "PEN12345678",
      "allowsSalarySacrifice": false,
      "defaultEmployeeContributionsPercent": 5,
      "defaultEmployerContributionsPercent": 3
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Widgets Inc",
      "status": "AwaitingAgreement",
      "createdAt": "2025-03-01T10:00:00Z",
      "companyNumber": "87654321",
      "paymentMethod": "BankTransfer",
      "contributionBasis": "QualifyingEarnings",
      "externalReference": "PEN87654321",
      "allowsSalarySacrifice": false,
      "defaultEmployeeContributionsPercent": 5,
      "defaultEmployerContributionsPercent": 3
    }
  ]
}
Response examples (401) 
{
  "error": "unauthorized"
}
Response examples (500) 
{
  "error": "internal server error"
}