# 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:

1. **AwaitingAgreement** — Employer record created, company validated
   against Companies House. The employer must complete onboarding on
   Penfold's platform (sign agreement, AML/KYB verification).
2. **Pending** — Onboarding complete, awaiting first payroll submission.
3. **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`.



## Servers
- Production: https://partner-api.getpenfold.com/v1 (Production)
- Staging: https://partner-api.getpenfold.dev/v1 (Staging)


## Authentication methods
- Bearer auth


## Parameters



### Body: application/json (object)

- **companyNumber** (string)
  Companies House registration number
- **companyName** (string)
  Registered company name
- **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
- **directorName** (string)
  Full name of a company director. Required for AML verification.
- **directorDateOfBirth** (string(date))
  Date of birth of the company director (YYYY-MM-DD). Required for AML verification.
- **payrollFrequencies** (array[string])
  How often the employer runs payroll
- **expectedFirstPayPeriodStartDate** (string(date))
  Expected start date of the first pay period (YYYY-MM-DD)
- **expectedPayPeriodCadence** (string)
  Expected cadence for pay periods
- **defaultEmployeeContributionsPercent** (number)
  Default employee contribution percentage
- **defaultEmployerContributionsPercent** (number)
  Default employer contribution percentage
- **contributionBasis** (string)
  Basis on which pension contributions are calculated
- **allowsSalarySacrifice** (boolean)
  Whether the employer allows salary sacrifice arrangements
- **paymentMethod** (string)
  How the employer will pay pension contributions
- **numberOfEmployees** (integer)
  Approximate number of employees to be enrolled


## Responses
### 201
Employer created successfully

#### Body: application/json (object)
- **id** (string(uuid))
  Unique identifier for the employer
- **name** (string)
  Employer name
- **externalReference** (string)
  Penfold employer reference (`PEN` + Companies House number)
- **companyNumber** (string)
  Companies House number
- **status** (string)
  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
- **defaultEmployeeContributionsPercent** (number)
  Default employee contribution percentage
- **defaultEmployerContributionsPercent** (number)
  Default employer contribution percentage
- **contributionBasis** (string)
  Basis on which pension contributions are calculated
- **allowsSalarySacrifice** (boolean)
  Whether the employer allows salary sacrifice
- **paymentMethod** (string)
  Payment method for pension contributions
- **createdAt** (string(date-time))
  When the employer was created (ISO 8601)

### 400
Request body failed validation

#### Body: application/json (object)
- **error** (string)
  A descriptive error message.
- **validationErrors** (array[object])


### 401
Missing or invalid authentication token

#### Body: application/json (object)
- **error** (string)


### 404
Company not found in Companies House

#### Body: application/json (object)
- **error** (string)


### 409
Employer already exists for this company number

#### Body: application/json (object)
- **error** (string)

- **externalReference** (string)
  The existing employer's Penfold reference

### 500
Internal server error

#### Body: application/json (object)
- **error** (string)



[Powered by Bump.sh](https://bump.sh)