Query parameters

• page_size integer

  The maximum number of employers to return per page.

  Minimum value is 1, maximum value is 500. Default value is 200.

• page_number integer

  The page number to return in the list of employers.

  Minimum value is 1. Default value is 1.

Responses

• 200 application/json

  List of employers retrieved successfully.

  Hide response attributes Show response attributes object

  • page_number integer Required

    The current page number.

  • page_size integer Required

    The number of employers per page.

  • total_items integer Required

    The total number of employers available.

  • items array[object] Required

    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 — indicates whether the employer permits salary sacrifice arrangements. 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.

    • aml_verification_status string

      The status of the employer company's AML verification.

      Values are Pending, Accepted, Failed, or Open.

    • status

      The status of the employer.

      Values are PendingPa, MissingDD, Pending, or Active. Default value is PendingPa.

    • direct_debit_mandate_status string

      The status of the employer's Direct Debit mandate. null means Penfold holds no mandate record for the employer.

      Values are PendingCustomerApproval, PendingSubmission, Submitted, Active, SuspendedByPayer, Failed, Cancelled, Expired, Consumed, or Blocked.

• 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.