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

PATCH /employers/{employer_id}

O auth2 client credentials

Update an employer's configuration. All fields are optional — only provided fields are updated.

application/json

Body Required

primary_contact_email string(email)

The email address of the employer primary contact.
primary_contact_role string

The role of the employer primary contact.

Values are CompanyDirector, Finance, or HR.
payroll_frequencies array[object]

Payroll frequencies to add for this employer. Additive only: each value is added if not already configured; existing frequencies are never removed by this field. Sending a frequency that is already set is a no-op.

At least 1 element.
Hide payroll_frequencies attributes Show payroll_frequencies attributes object
- frequency string Required
  
  The desired frequency ie Weekly, Fortnightly, FourWeekly, Monthly
  
  Values are Weekly, Fortnightly, FourWeekly, or Monthly.
- expected_first_pay_period_start_date string(date) Required
  
  Expected start date of the first pay period (YYYY-MM-DD)
default_employer_contributions_percent number

The default contribution percentage for the employer.

Minimum value is 0, maximum value is 100.
default_employee_contributions_percent number

The default contribution percentage for the employee.

Minimum value is 0, maximum value is 100.
contribution_basis string

The basis on which the employer makes pension contributions.

Values are QualifyingEarnings, TotalPay, or BasicPay.
allows_salary_sacrifice boolean

Whether the employer allows for salary sacrifice.
payment_method string

The payment method used by the employer.

Value is BankTransfer.

Responses

200 application/json

Employer updated 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

Request body failed validation
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

Missing or invalid authentication token
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
404 application/json

Resource not found
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.
500 application/json

Internal server error
Hide response attribute Show response attribute object
- error string
  
  A descriptive error message.

PATCH /employers/{employer_id}

curl \
 --request PATCH 'https://payroll-api.getpenfold.dev/v4/employers/{employer_id}' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"primary_contact_email":"john.doe@example.com","primary_contact_role":"CompanyDirector","payroll_frequencies":[{"frequency":"Monthly","expected_first_pay_period_start_date":"2025-03-01"}],"default_employer_contributions_percent":3,"default_employee_contributions_percent":5,"contribution_basis":"QualifyingEarnings","allows_salary_sacrifice":false,"payment_method":"BankTransfer"}'

Request examples

{
  "primary_contact_email": "john.doe@example.com",
  "primary_contact_role": "CompanyDirector",
  "payroll_frequencies": [
    {
      "frequency": "Monthly",
      "expected_first_pay_period_start_date": "2025-03-01"
    }
  ],
  "default_employer_contributions_percent": 3,
  "default_employee_contributions_percent": 5,
  "contribution_basis": "QualifyingEarnings",
  "allows_salary_sacrifice": false,
  "payment_method": "BankTransfer"
}

Response examples (200)

{
  "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 (404)

{
  "error": "Bad request: invalid data provided."
}

Response examples (500)

{
  "error": "Bad request: invalid data provided."
}