# Create new employees for a specified employer

**POST /employers/{employer_id}/employees**

Create new employees for a specified employer. **Asynchronous** — the response is an `Upload` object representing queued work, not a final result. Member identifiers are not available in this response; poll `GET /uploads/{upload_id}` until the status is terminal, then fetch enrolments via `GET /uploads/{upload_id}/enrolments` and any errors via `GET /uploads/{upload_id}/errors`. Processing is idempotent: re-submitting the same records will only process those not already enrolled successfully.



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


## Authentication methods
- O auth2 client credentials


## Parameters

### Path parameters

- **employer_id** (string)



### Body: application/json (array[object])
Employee creation data.
- **email** (string(email))
  Email address of the employee.

- **forename** (string)
  The employee's first name.

- **surname** (string)
  The employee's last name.

- **title** (string)
  The employee's title, e.g. Mr., Mrs., Dr., etc.

- **date_of_birth** (string(date))
  The employee's date of birth, in YYYY-MM-DD format.

- **address_line1** (string)
  The first line of the employee's address.

- **postcode** (string)
  The postal code of the employee's address.

- **national_insurance_number** (string(national_insurance_number))
  The employee's National Insurance number.

- **employment_start_date** (string(date))
  The date the employee started their employment, in YYYY-MM-DD format.



## Responses
### 201
Submission created successfully for the employees.

#### Body: application/json (object)
- **id** (string)
  ID of the upload.

- **employer_id** (string | null)
  ID of the employer the upload was made for.

- **put_destination_url** (string | null)
  Destination URL where the actual file should be sent, using a PUT request. Only present when status is AwaitingFile. We recommend using the AWS S3 client SDK to perform the upload.

- **created_at** (string(date-time))
  Datetime the upload was created.

- **updated_at** (string(date-time))
  Datetime the upload was last updated.

- **processing_started** (string(date-time) | null)
  Datetime of when processing of the file began.

- **processing_ended** (string(date-time) | null)
  Datetime of when processing of the file ended, or null if it has not ended.

- **processing_time** (number | null)
  The number of seconds it took to process the file end-to-end (if applicable).

- **total_errors** (number)
  The number of errors produced in processing the file. Zero if there are none or processing is not finished. Use the `{upload_id}/errors` endpoint to retrieve detailed information of the errors.

- **contributions_created** (number)
  The number of contributions created during processing. Zero if processing is not finished.

- **contributions_unprocessed** (number)
  The number of contributions that failed to be created during processing. Zero if processing is not finished.

- **contributions_already_existed** (number)
  The number of contributions that already existed prior to processing, and which have been skipped during processing of the upload. Zero if processing is not finished.

- **employer_contributions** (number)
  The total of employer contributions created for the upload, excluding contributions that already existed. Zero if processing is not finished.

- **employee_contributions** (number)
  The total of employee contributions created for the upload, excluding contributions that already existed. Zero if processing is not finished.

- **total_contributions** (number)
  The total of contributions created for the upload, excluding contributions that already existed. Zero if processing is not finished.

- **filename** (string | null)
  The filename of the uploaded file (if applicable).

- **status** (string)
  The status of the upload. `Error` indicates the file was not able to be processed. `PartiallyProcessed` indicates that validation passed and processing ran eagerly, but some records succeeded while others produced errors — treat this status as **incomplete** and re-submit the failing records (or the entire file) to recover. Processing is idempotent per pay period, so successfully-processed records will be skipped on re-submission. To retrieve the errors for an `Error` or `PartiallyProcessed` upload, use the `/uploads/{upload_id}/errors` endpoint.


### 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, the request requires authentication, and the provided credentials are either missing or incorrect.

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


### 404
Employer not found, the specified employer_id does not match any existing employer.

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



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