Create employer

POST /employers

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

Onboarding lifecycle

Employer creation triggers an onboarding process:

AwaitingAgreement — Employer record created, company validated against Companies House. The employer must complete onboarding on Penfold's platform (sign agreement, AML/KYB verification).
Pending — Onboarding complete, awaiting first payroll submission.
Active — First payroll processed. Employer is fully operational.

Poll GET /employers or GET /employers/{employerId} to track status progression. The employer cannot process payroll until status is Active.

application/json

Body Required

companyNumber string Required

Companies House registration number
companyName string Required

Registered company name
primaryContactEmail string(email) Required

Email address of the primary contact at the employer
primaryContactName string Required

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.
directorName string Required

Full name of a company director. Required for AML verification.
directorDateOfBirth string(date) Required

Date of birth of the company director (YYYY-MM-DD). Required for AML verification.
payrollFrequencies array[string] Required

How often the employer runs payroll

Values are Weekly, Fortnightly, FourWeekly, or Monthly.
expectedFirstPayPeriodStartDate string(date) Required

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

Expected cadence for pay periods

Values are Weekly, Fortnightly, FourWeekly, or Monthly.
defaultEmployeeContributionsPercent number Required

Default employee contribution percentage

Minimum value is 0, maximum value is 100.
defaultEmployerContributionsPercent number Required

Default employer contribution percentage

Minimum value is 0, maximum value is 100.
contributionBasis string Required

Basis on which pension contributions are calculated

Values are QualifyingEarnings, TotalPay, or BasicPay.
allowsSalarySacrifice boolean

Whether the employer allows salary sacrifice arrangements

Default value is false.
paymentMethod string Required

How the employer will pay pension contributions

Value is BankTransfer.
numberOfEmployees 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
Alias for Employer — returned from POST /employers.
- 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

Company not found in Companies House
Hide response attribute Show response attribute object
- error string Required
409 application/json

Employer already exists for this company number
Hide response attributes Show response attributes object
- error string Required
- externalReference string Required
  
  The existing employer's Penfold reference
500 application/json

Internal server error
Hide response attribute Show response attribute object
- error string Required

POST /employers

curl \
 --request POST 'https://partner-api.getpenfold.com/v1/employers' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"companyName":"Acme Ltd","directorName":"John Smith","companyNumber":"12345678","paymentMethod":"BankTransfer","contributionBasis":"QualifyingEarnings","numberOfEmployees":50,"payrollFrequencies":["Monthly"],"primaryContactName":"Jane Smith","primaryContactRole":"PayrollManager","directorDateOfBirth":"1980-05-15","primaryContactEmail":"payroll@acme.com","allowsSalarySacrifice":false,"expectedPayPeriodCadence":"Monthly","expectedFirstPayPeriodStartDate":"2025-03-01","defaultEmployeeContributionsPercent":5,"defaultEmployerContributionsPercent":3}'

Request example

{
  "companyName": "Acme Ltd",
  "directorName": "John Smith",
  "companyNumber": "12345678",
  "paymentMethod": "BankTransfer",
  "contributionBasis": "QualifyingEarnings",
  "numberOfEmployees": 50,
  "payrollFrequencies": [
    "Monthly"
  ],
  "primaryContactName": "Jane Smith",
  "primaryContactRole": "PayrollManager",
  "directorDateOfBirth": "1980-05-15",
  "primaryContactEmail": "payroll@acme.com",
  "allowsSalarySacrifice": false,
  "expectedPayPeriodCadence": "Monthly",
  "expectedFirstPayPeriodStartDate": "2025-03-01",
  "defaultEmployeeContributionsPercent": 5,
  "defaultEmployerContributionsPercent": 3
}

Response examples (201)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Ltd",
  "status": "AwaitingAgreement",
  "createdAt": "2025-03-01T10:00:00Z",
  "companyNumber": "12345678",
  "paymentMethod": "BankTransfer",
  "contributionBasis": "QualifyingEarnings",
  "externalReference": "PEN12345678",
  "allowsSalarySacrifice": false,
  "defaultEmployeeContributionsPercent": 5,
  "defaultEmployerContributionsPercent": 3
}

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": "company not found in Companies House"
}

Response examples (409)

{
  "error": "employer already exists",
  "externalReference": "PEN12345678"
}

Response examples (500)

{
  "error": "internal server error"
}