Penfold Partner API

Create employer

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
O auth2 client credentials

Creates a new employer under your organisation.

The company number is validated against Companies House. If an employer with the same company number already exists in your organisation, a 409 is returned with the existing employer's external_reference.

application/json

Body Required

  • company_number string Required

    Companies House registration number

  • company_name string Required

    Registered company name

  • primary_contact_email string(email) Required

    Email address of the primary contact at the employer

  • primary_contact_role string

    Role of the primary contact at the employer

    Values are CompanyDirector, Finance, or HR.

  • payroll_frequencies array Required

    How often the employer runs payroll

  • expected_first_pay_period_start_date string(date) Required

    Expected start date of the first pay period (YYYY-MM-DD)

  • expected_pay_period_cadence string Required

    Expected cadence for pay periods

  • default_employee_contributions_percent number Required

    Default employee contribution percentage

    Minimum value is 0, maximum value is 100.

  • default_employer_contributions_percent number Required

    Default employer contribution percentage

    Minimum value is 0, maximum value is 100.

  • contribution_basis string Required

    Basis on which pension contributions are calculated

  • allows_salary_sacrifice boolean

    Whether the employer allows salary sacrifice arrangements

    Default value is false.

  • payment_method string Required

    How the employer will pay pension contributions

  • number_of_employees integer Required

    Approximate number of employees to be enrolled

    Minimum value is 1.

Responses

  • 201 application/json

    Employer created successfully

    Hide response attributes Show response 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

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 403 application/json

    Forbidden

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 404 application/json

    Company not found in Companies House

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 405 application/json

    Method not allowed

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
  • 409 application/json

    Employer already exists for this company number

    Hide response attributes Show response attributes object
    • error string Required
    • external_reference string Required

      The existing employer's Penfold reference
  • 500 application/json

    Internal server error

    Hide response attribute Show response attribute object
    • error string

      A descriptive error message.
POST /employers 
curl \
 --request POST 'https://payroll-api.getpenfold.dev/v4/employers' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"company_number":"12345678","company_name":"Acme Ltd","primary_contact_email":"payroll@acme.com","primary_contact_role":"HR","payroll_frequencies":["Monthly"],"expected_first_pay_period_start_date":"2025-03-01","expected_pay_period_cadence":"TaxYear","default_employee_contributions_percent":5,"default_employer_contributions_percent":3,"contribution_basis":"QualifyingEarnings","allows_salary_sacrifice":false,"payment_method":"BankTransfer","number_of_employees":50}'
Request examples 
{
  "company_number": "12345678",
  "company_name": "Acme Ltd",
  "primary_contact_email": "payroll@acme.com",
  "primary_contact_role": "HR",
  "payroll_frequencies": [
    "Monthly"
  ],
  "expected_first_pay_period_start_date": "2025-03-01",
  "expected_pay_period_cadence": "TaxYear",
  "default_employee_contributions_percent": 5,
  "default_employer_contributions_percent": 3,
  "contribution_basis": "QualifyingEarnings",
  "allows_salary_sacrifice": false,
  "payment_method": "BankTransfer",
  "number_of_employees": 50
}
Response examples (201) 
{
  "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."
}
Response examples (403) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (404) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (405) 
{
  "error": "Bad request: invalid data provided."
}
Response examples (409) 
{
  "error": "employer already exists",
  "external_reference": "PEN12345678"
}
Response examples (500) 
{
  "error": "Bad request: invalid data provided."
}