POST
Create Employee

Authorizations

Authorization
string
header
required

Get token from Auth0 and paste it here

Headers

X-Acting-User
string | null

The person acting through the access credential, recorded as created_by of what the request writes. Audit only: access is checked on the credential.

Required string length: 1 - 255

Path Parameters

organization_id
string
required

Body

application/json

Creating an employee: the hub, valid_from, core, and any other satellites. Each satellite sent starts on [valid_from, 9999-12-31). One not sent is not created: it reads as null until a PUT writes it, so an employee created without job is in no pay group until then.

valid_from
string<date>
required

The first day every satellite's data is valid at

core
GBEmployeeCore · object
required

Identity of the person, as payroll and filing need it.

Each name field holds one name: a person with several middle names sends the one that should appear on HMRC returns. If only initials are known, they go one per field (first_name "J", middle_name "M"). An optional name the person does not have is null.

external_ref
string

The integrator's own stable key, unique within the organization. Generated when absent.

Required string length: 1 - 255
address
GBEmployeeAddress · object

The person's residence address, as filed to HMRC.

job
GBEmployeeJob · object

The terms of the employment as a client writes them.

tax
GBEmployeeTax · object
insurance
GBEmployeeInsurance · object
compensation
GBEmployeeCompensation · object

Standing pay elements.

bank
GBEmployeeBank · object

Response

Successful Response

The employee with every satellite as it reads on one date. A satellite never written, or with no slice on an explicit date, is null.

id
string
required
external_ref
string | null
required
created_at
string<date-time>
required
read-only
created_by
string
required
read-only

Who created the hub: the acting user (X-Acting-User, else the access credential), system for our own writes, or <authority>:<notice> for a write on an authority's behalf, e.g. hmrc:P6.

deleted_at
string<date-time> | null
required

When the hub was closed

organization_id
string
required
status
GBEmployeeStatus · object
required

The read-only status satellite. It carries no fields; it exists so that every employee read has a status object.

core
GBEmployeeCoreSatellite · object | null
address
GBEmployeeAddressSatellite · object | null
job
GBEmployeeJobSatellite · object | null
tax
GBEmployeeTaxSatellite · object | null
insurance
GBEmployeeInsuranceSatellite · object | null
compensation
GBEmployeeCompensationSatellite · object | null
bank
GBEmployeeBankSatellite · object | null