Penfold Partner API
PATCH /employers/{employerId}
Bearer auth

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

Path parameters

  • employerId string(uuid) Required

    Penfold employer UUID

application/json

Body Required

  • primaryContactEmail string(email)

    Email address of the primary contact at the employer

  • primaryContactName string

    Full name of the primary contact at the employer

  • primaryContactRole string

    Role of the primary contact at the employer

    Values are CompanyDirector, Finance, HR, or PayrollManager.

  • defaultEmployeeContributionsPercent number

    Default employee contribution percentage

    Minimum value is 0, maximum value is 100.

  • defaultEmployerContributionsPercent number

    Default employer contribution percentage

    Minimum value is 0, maximum value is 100.

  • contributionBasis string

    Basis on which pension contributions are calculated

    Values are QualifyingEarnings, TotalPay, or BasicPay.

  • allowsSalarySacrifice boolean

    Whether the employer allows salary sacrifice arrangements

  • payrollFrequencies array[string]

    How often the employer runs payroll

    Values are Weekly, Fortnightly, FourWeekly, or Monthly.

Responses

  • 200 application/json

    Employer updated successfully.

    Hide response attributes Show response 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)
  • 400 application/json

    Request body failed validation

    Hide response attributes Show response attributes object
    • error string Required

      A descriptive error message.

    • validationErrors array[object]
      Hide validationErrors attributes Show validationErrors 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 Required
  • 404 application/json

    Resource not found

    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
PATCH /employers/{employerId} 
curl \
 --request PATCH 'https://partner-api.getpenfold.com/v1/employers/{employerId}' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"defaultEmployeeContributionsPercent":6,"defaultEmployerContributionsPercent":4}'
Request examples 
{
  "defaultEmployeeContributionsPercent": 6,
  "defaultEmployerContributionsPercent": 4
}
{
  "primaryContactName": "John Doe",
  "primaryContactRole": "Finance",
  "primaryContactEmail": "new.contact@acme.com"
}
Response examples (200) 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Ltd",
  "externalReference": "PEN12345678",
  "companyNumber": "12345678",
  "status": "Active",
  "defaultEmployeeContributionsPercent": 5,
  "defaultEmployerContributionsPercent": 3,
  "contributionBasis": "QualifyingEarnings",
  "allowsSalarySacrifice": false,
  "paymentMethod": "BankTransfer",
  "createdAt": "2025-03-01T10:00:00Z"
}
Response examples (400) 
{
  "error": "validation failed",
  "validationErrors": [
    {
      "field": "companyNumber",
      "message": "companyNumber is required"
    },
    {
      "field": "primaryContactEmail",
      "message": "must be a valid email address"
    }
  ]
}
Response examples (401) 
{
  "error": "unauthorized"
}
Response examples (404) 
{
  "error": "not found"
}
Response examples (500) 
{
  "error": "internal server error"
}