# 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 external_reference.



## Servers
- https://payroll-api.getpenfold.dev/v4: https://payroll-api.getpenfold.dev/v4 ()


## Authentication methods
- O auth2 client credentials


## Parameters



### Body: application/json (object)

- **company_number** (string)
  Companies House registration number

- **company_name** (string)
  Registered company name

- **primary_contact_email** (string(email))
  Email address of the primary contact at the employer

- **primary_contact_role** (string)
  Role of the primary contact at the employer

- **payroll_frequencies** (array)
  How often the employer runs payroll

- **expected_first_pay_period_start_date** (string(date))
  Expected start date of the first pay period (YYYY-MM-DD)

- **expected_pay_period_cadence** (string)
  Expected cadence for pay periods

- **default_employee_contributions_percent** (number)
  Default employee contribution percentage

- **default_employer_contributions_percent** (number)
  Default employer contribution percentage

- **contribution_basis** (string)
  Basis on which pension contributions are calculated

- **allows_salary_sacrifice** (boolean)
  Whether the employer allows salary sacrifice arrangements

- **payment_method** (string)
  How the employer will pay pension contributions

- **number_of_employees** (integer)
  Approximate number of employees to be enrolled



## Responses
### 201
Employer created successfully

#### Body: application/json (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.

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

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

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

- **default_employee_contributions_percent** (number | null)
  Default employee contribution percentage.

- **default_employer_contributions_percent** (number | null)
  Default employer contribution percentage.

- **status** ()
  The status of the employer.


### 400
Bad request, the request is malformed or contains invalid data.

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

- **validation_errors** (array[object])


### 401
Unauthorized

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


### 403
Forbidden

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


### 404
Company not found in Companies House

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


### 405
Method not allowed

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


### 409
Employer already exists for this company number

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

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


### 500
Internal server error

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



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