API ReferenceEmployees

Create an employee

Creates an employee with the linked employer. If the employer has an active health insurance scheme that automatically provides insurance to employees the employee will be enrolled.

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Headers

Idempotency-KeystringOptional

Unique key to ensure idempotent requests. If the same key is used for multiple identical & successful requests, the same response will be returned. Read more here

Request

This endpoint expects an object.
employer_idstringRequiredformat: "er_.+"
first_namestringRequired

It can include the middle name. Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.

last_namestringRequired

Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.

date_of_birthdateRequired

Must be in the past, but after 1900-01-01

sex_at_birthenumRequired
The sex assigned to the employee at birth
Allowed values:
home_addressobjectRequired
Location where the employee is legally registered to live
national_tax_idstringRequired

PPSN in Ireland, NINo in the UK, DNI/NIE in Spain. Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.

start_ondateRequired

Employment start date. Must be after 1900-01-01, can be in the future

phone_numberstringRequired

Phone number in E.164 international format (e.g. +447700900999). NOTE: This field will be normalized according to our internal formatting rules.

emailstringRequired

Must not be empty. NOTE: This field will be normalized according to our internal formatting rules.

external_customer_idstring or nullOptional

A unique identifier assigned by the Employer of Record (EoR) platform to the Customer (i.e. the company using the EoR service) for which the employee is employed. This ID groups employees under this Customer, enabling the aggregation of contribution reporting and other values per Customer rather than per legal entity. This parameter is only required for EoR platforms.

nationalityenum or nullOptional
earliest_benefits_start_datedate or nullOptional
The earliest date this employee can be enrolled in any benefits. Before this date, the employee remains in a Pending state and is excluded from benefit activation. **Constraints:** - Must be a valid date. - Ignored for statutory schemes where immediate coverage is legally required. Example: Local Netherlands and UAE schemes.
bank_accountobject or nullOptional
Bank account details
metadatamap from strings to strings or nullOptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Maximum 25 keys. Individual keys can be up to 40 characters and values up to 500 characters.

Response

OK
first_namestring
First name of the employee. It can include the middle name
last_namestring
Last name of the employee
date_of_birthdate
Date of birth of the employee
sex_at_birthenum
The sex assigned to the employee at birth
Allowed values:
national_tax_idstring

PPSN in Ireland, NINo in the UK, DNI/NIE in Spain

phone_numberstring

Phone number in E.164 international format (e.g. +447700900999)

emailstring
Email address of the employee
platform_idstring or nullformat: "pt_.+"
Unique identifier for the platform
idstring or nullformat: "ee_.+"
Unique identifier for the employee
employer_idstring or nullformat: "er_.+"
Unique identifier for the employer
statusenum or null
Current status of the employee
Allowed values:
external_customer_idstring or null

A unique identifier assigned by the Employer of Record (EoR) platform to the Customer (i.e. the company using the EoR service) for which the employee is employed. This ID groups employees under this Customer, enabling the aggregation of contribution reporting and other values per Customer rather than per legal entity. This parameter is only available to EoR platforms.

home_addressobject or null
Location where the employee is legally registered to live
nationalityenum or null

Nationality of the employee (e.g. IE for Ireland, GB for United Kingdom, ES for Spain)

start_ondate or null
Employment start date
earliest_benefits_start_datedate or null

The earliest date this employee can be enrolled in any benefits. Before this date, the employee remains in a Pending state and is excluded from benefit activation. Ignored for statutory schemes where immediate coverage is legally required. Example: Local Netherlands and UAE schemes.

offboard_ondatetime or null
Date when the employee was or will be offboarded
bank_accountobject or null
Bank account details
metadatamap from strings to strings or null

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Maximum 25 keys. Individual keys can be up to 40 characters and values up to 500 characters.

objectstring or null
The object type

Errors