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

{
  "Penfold Payroll API v4 MCP server": {
    "url": "https://docs.getpenfold.dev/mcp"
  }
}

PATCH /employers/{employer_id}

O auth2 client credentials

Partner organisations only. A Payroll organisation calling this endpoint receives 405 Method Not Allowed.

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.

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 — 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

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

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
}

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,
  "aml_verification_status": "Pending",
  "status": "Active",
  "direct_debit_mandate_status": "PendingCustomerApproval"
}

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