Enrol new employees for a specified employer. Employees are processed asynchronously — the response returns an upload ID that can be used to track processing status via the Uploads endpoints.
Body
Required
-
Email address of the employee.
-
The employee's first name.
-
The employee's last name.
-
The employee's title, e.g. Mr., Mrs., Dr., etc.
-
The employee's date of birth, in YYYY-MM-DD format.
-
The first line of the employee's address.
-
The postal code of the employee's address.
-
The employee's National Insurance number.
-
The date the employee started their employment, in YYYY-MM-DD format.
POST
/employers/{employerId}/employees
curl \
--request POST 'https://partner-api.getpenfold.com/v1/employers/{employerId}/employees' \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '[{"email":"john.doe@example.com","forename":"John","surname":"Doe","title":"Mr.","dateOfBirth":"1990-01-01","addressLine1":"123 Main Street","postcode":"AB12 3CD","nationalInsuranceNumber":"AA123456C","employmentStartDate":"2023-01-01"}]'
Request examples
[
{
"email": "john.doe@example.com",
"forename": "John",
"surname": "Doe",
"title": "Mr.",
"dateOfBirth": "1990-01-01",
"addressLine1": "123 Main Street",
"postcode": "AB12 3CD",
"nationalInsuranceNumber": "AA123456C",
"employmentStartDate": "2023-01-01"
}
]
Response examples (201)
{
"id": "u1234-abcd-5678-efgh",
"status": "ReceivedFile",
"createdAt": "2023-03-01T12: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"
}