Retrieve an employee

GET

/employees/:employee_id

GET

/employees/:employee_id

$ curl https://test.api.kota.io/employees/ee_3b1333d87d9d4fd6ad83ba7f6b0e951a \
>      -H "Authorization: Bearer <token>"

1 {
2   "first_name": "Emily",
3   "last_name": "Johnson",
4   "date_of_birth": "1985-07-23",
5   "sex_at_birth": "female",
6   "national_tax_id": "AB123456C",
7   "phone_number": "+441632960123",
8   "email": "emily.johnson@example.com",
9   "platform_id": "pt_9f8e7d6c5b4a3210fedcba9876543210",
10   "id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
11   "employer_id": "er_7a6b5c4d3e2f1098abcdef1234567890",
12   "status": "active",
13   "external_customer_id": null,
14   "home_address": null,
15   "nationality": null,
16   "start_on": "2022-05-15",
17   "earliest_benefits_start_date": "2022-05-15",
18   "offboard_on": null,
19   "bank_account": null,
20   "metadata": {
21     "department": "Engineering",
22     "employee_level": "Senior"
23   },
24   "object": "employee"
25 }

Retrieves an employee object.

Authentication

AuthorizationBearer

Authorization header using the Bearer scheme

Path parameters

employee_idstringRequiredformat: "ee_.+"

Response

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

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_idstringOptionalformat: "pt_.+"

Unique identifier for the platform

idstringOptionalformat: "ee_.+"

Unique identifier for the employee

employer_idstringOptionalformat: "er_.+"

Unique identifier for the employer

statusenumOptional

Current status of the employee

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 available to EoR platforms.

home_addressobjectOptional

Location where the employee is legally registered to live

nationalityenumOptional

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

start_ondateOptional

Employment start date

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. Ignored for statutory schemes where immediate coverage is legally required. Example: Local Netherlands and UAE schemes.

offboard_ondatetime or nullOptional

Date when the employee was or will be offboarded

bank_accountobjectOptional

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.

objectstringOptionalRead-only

The object type

Errors

400

Bad Request Error

404

Not Found Error