Employees

Offboard an employee

Changed on

Schedules an employee to be offboarded. Changes affecting payroll will be reflected in the next available payroll cycle data run. Offboarding an employee can be cancelled up to, and including, the day before they are scheduled for offboarding. A webhook is available to inform you when this completes.

post/employees/{employee_id}/offboard

Request

  • Base URL
    https://test.api.kota.io
  • URL
    https://test.api.kota.io/employees/{employee_id}/offboard
  • Auth
    HTTP bearer

Path parameters

employee_idstring required
Example:ee_3b1333d87d9d4fd6ad83ba7f6b0e951a

Headers

Idempotency-Keystring

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 body

offboard_onstring date-time required

The date when the employee should be offboarded. Can be a future date, today, or up to 30 days in the past if the employee has active insurance policies. Past dates beyond 30 days are allowed only if there are no active policies.

offboard_reasonstring required

Example request

{
  "offboard_on": "2024-12-01T00:00:00Z"
}

Response

OK

platform_idstring

Unique identifier for the platform

idstring

Unique identifier for the employee

employer_idstring

Unique identifier for the employer

status'pending' | 'active' | 'offboarding' | 'inactive' | 'restricted'
external_customer_idstring nullable

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.

first_namestring required

First name of the employee. It can include the middle name

last_namestring required

Last name of the employee

date_of_birthstring date required

Date of birth of the employee

sex_at_birth'male' | 'female' required
nationality'af' | 'ax' | 'al' | 'dz' | 'as' | 'ad' | 'ao' | 'ai' | 'aq' | 'ag' | 'ar' | 'am' | 'aw' | 'au' | 'at' | 'az' | 'bs' | 'bh' | 'bd' | 'bb' | 'by' | 'be' | 'bz' | 'bj' | 'bm' | 'bt' | 'bo' | 'bq' | 'ba' | 'bw' | 'bv' | 'br' | 'io' | 'bn' | 'bg' | 'bf' | 'bi' | 'cv' | 'kh' | 'cm' | 'ca' | 'ky' | 'cf' | 'td' | 'cl' | 'cn' | 'cx' | 'cc' | 'co' | 'km' | 'cg' | 'cd' | 'ck' | 'cr' | 'ci' | 'hr' | 'cu' | 'cw' | 'cy' | 'cz' | 'dk' | 'dj' | 'dm' | 'do' | 'ec' | 'eg' | 'sv' | 'gq' | 'er' | 'ee' | 'sz' | 'et' | 'fk' | 'fo' | 'fj' | 'fi' | 'fr' | 'gf' | 'pf' | 'tf' | 'ga' | 'gm' | 'ge' | 'de' | 'gh' | 'gi' | 'gr' | 'gl' | 'gd' | 'gp' | 'gu' | 'gt' | 'gg' | 'gn' | 'gw' | 'gy' | 'ht' | 'hm' | 'va' | 'hn' | 'hk' | 'hu' | 'is' | 'in' | 'id' | 'ir' | 'iq' | 'ie' | 'im' | 'il' | 'it' | 'jm' | 'jp' | 'je' | 'jo' | 'kz' | 'ke' | 'ki' | 'kp' | 'kr' | 'xk' | 'kw' | 'kg' | 'la' | 'lv' | 'lb' | 'ls' | 'lr' | 'ly' | 'li' | 'lt' | 'lu' | 'mo' | 'mg' | 'mw' | 'my' | 'mv' | 'ml' | 'mt' | 'mh' | 'mq' | 'mr' | 'mu' | 'yt' | 'mx' | 'fm' | 'md' | 'mc' | 'mn' | 'me' | 'ms' | 'ma' | 'mz' | 'mm' | 'na' | 'nr' | 'np' | 'nl' | 'nc' | 'nz' | 'ni' | 'ne' | 'ng' | 'nu' | 'nf' | 'mk' | 'mp' | 'no' | 'om' | 'pk' | 'pw' | 'ps' | 'pa' | 'pg' | 'py' | 'pe' | 'ph' | 'pn' | 'pl' | 'pt' | 'pr' | 'qa' | 're' | 'ro' | 'ru' | 'rw' | 'bl' | 'sh' | 'kn' | 'lc' | 'mf' | 'pm' | 'vc' | 'ws' | 'sm' | 'st' | 'sa' | 'sn' | 'rs' | 'sc' | 'sl' | 'sg' | 'sx' | 'sk' | 'si' | 'sb' | 'so' | 'za' | 'gs' | 'ss' | 'es' | 'lk' | 'sd' | 'sr' | 'sj' | 'se' | 'ch' | 'sy' | 'tw' | 'tj' | 'tz' | 'th' | 'tl' | 'tg' | 'tk' | 'to' | 'tt' | 'tn' | 'tr' | 'tm' | 'tc' | 'tv' | 'ug' | 'ua' | 'ae' | 'gb' | 'um' | 'us' | 'uy' | 'uz' | 'vu' | 've' | 'vn' | 'vg' | 'vi' | 'wf' | 'eh' | 'ye' | 'zm' | 'zw'
national_tax_idstring required

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

start_onstring date

Employment start date

earliest_benefits_start_datestring date nullable

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.

phone_numberstring nullable required

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

emailstring required

Email address of the employee

offboard_onstring date-time nullable

Date when the employee was or will be offboarded

metadataobject nullable

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

The object type

Example response

{
  "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "date_of_birth": "2024-12-01",
  "start_on": "2024-12-01",
  "earliest_benefits_start_date": "2024-12-01",
  "offboard_on": "2024-12-01T00:00:00Z"
}

Changes