> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server. # Create an employee POST https://test.api.kota.io/employees Content-Type: application/json 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. Reference: https://docs.kota.io/api-reference/employees/create-employee ## Authentication - `Authorization` header (bearer token, required) — Authorization header using the Bearer scheme ## Servers - `https://test.api.kota.io` (test, default) - `https://api.kota.io` (production) ## Request ### Headers - `Idempotency-Key` (string, optional) — 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](/api#idempotent-requests) - `X-Platform-Id` (string, optional) — The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers. ### Body (application/json) This endpoint expects a CreateEmployeeRequest. - `employer_id` (string, required) - `first_name` (string, required) — It can include the middle name. Must not be empty. NOTE: This field will be normalized according to our internal formatting rules. - `last_name` (string, required) — Must not be empty. NOTE: This field will be normalized according to our internal formatting rules. - `date_of_birth` (date, required) — Must be in the past, but after 1900-01-01 - `sex_at_birth` (enum, required) — The sex assigned to the employee at birth - Allowed values: `male`, `female` - `home_address` (AddressModel, required) — Location where the employee is legally registered to live - `national_tax_id` (string, required) — Required in Ireland (PPSN), UK (NINo), Spain (DNI/NIE). It can be left empty for other countries. NOTE: This field will be normalized according to our internal formatting rules. - `start_on` (date, required) — Employment start date. Must be after 1900-01-01, can be in the future - `email` (string, required) — Must not be empty. NOTE: This field will be normalized according to our internal formatting rules. - `external_customer_id` (string, optional, 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 required for EoR platforms. - `nationality` (enum, optional) - Allowed values: `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` - `earliest_benefits_start_date` (date, optional, 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. **Constraints:** - Must be a valid date. - Ignored for statutory schemes where immediate coverage is legally required. Example: Local Netherlands and UAE schemes. - `phone_number` (string, optional, nullable) — Phone number in E.164 international format (e.g. +447700900999). Required when the home address is in Ireland, Spain or Denmark. NOTE: This field will be normalized according to our internal formatting rules. - `bank_account` (CreateEmployeeBankAccount, optional) — Bank account details - `metadata` (map from string to string, optional, 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. ## Response ### 200 OK - `first_name` (string, required) — First name of the employee. It can include the middle name - `last_name` (string, required) — Last name of the employee - `date_of_birth` (date, required) — Date of birth of the employee - `sex_at_birth` (enum, required) — The sex assigned to the employee at birth - Allowed values: `male`, `female` - `national_tax_id` (string, required) — PPSN in Ireland, NINo in the UK, DNI/NIE in Spain - `phone_number` (string, required, nullable) — Phone number in E.164 international format (e.g. +447700900999) - `email` (string, required) — Email address of the employee - `platform_id` (string, optional) — Unique identifier for the platform - `id` (string, optional) — Unique identifier for the employee - `employer_id` (string, optional) — Unique identifier for the employer - `status` (enum, optional) — Current status of the employee - Allowed values: `pending`, `active`, `offboarding`, `inactive`, `restricted` - `external_customer_id` (string, optional, 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. - `home_address` (AddressModel, optional) — Location where the employee is legally registered to live - `nationality` (enum, optional) — Nationality of the employee (e.g. IE for Ireland, GB for United Kingdom, ES for Spain) - Allowed values: `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` - `start_on` (date, optional) — Employment start date - `earliest_benefits_start_date` (date, optional, 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. - `offboard_on` (datetime, optional, nullable) — Date when the employee was or will be offboarded - `bank_account` (EmployeeBankAccount, optional) — Bank account details - `metadata` (map from string to string, optional, 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. - `object` (string, optional) — The object type ## Errors ### 400 Bad Request Error Bad Request - `type` (string, optional, nullable) - `title` (string, optional, nullable) - `status` (integer, optional, nullable) - `detail` (string, optional, nullable) - `instance` (string, optional, nullable) - `errors` (map from string to list of string, optional) ## Types ### AddressModel - `line1` (string, required) — Must not be empty. NOTE: This field will be normalized according to our internal formatting rules. - `city` (string, required) — Must not be empty. NOTE: This field will be normalized according to our internal formatting rules. - `postal_code` (string, required) — Must not be empty, and a valid postal code for the specified country. NOTE: This field will be normalized according to our internal formatting rules. - `country_code` (enum, required) - Allowed values: `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` - `line2` (string, optional, nullable) — NOTE: This field will be normalized according to our internal formatting rules. - `line3` (string, optional, nullable) — NOTE: This field will be normalized according to our internal formatting rules. - `state` (string, optional, nullable) — Required for United States (State), and Canada (Province). NOTE: This field will be normalized according to our internal formatting rules. ### CreateEmployeeBankAccount - `account_number` (string, required) — Account number in IBAN format. NOTE: This field will be normalized according to our internal formatting rules. ### EmployeeBankAccount - `account_number_last4` (string, required) — Last 4 digits of the account number ## Examples **Request** ```json { "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "first_name": "string", "last_name": "string", "date_of_birth": "2024-12-01", "sex_at_birth": "male", "home_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" }, "national_tax_id": "string", "start_on": "2024-12-01", "email": "string" } ``` **Response** ```json { "first_name": "string", "last_name": "string", "date_of_birth": "2024-12-01", "sex_at_birth": "male", "national_tax_id": "string", "phone_number": null, "email": "string", "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a", "id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a", "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "status": "pending", "external_customer_id": null, "home_address": null, "nationality": null, "start_on": "2024-12-01", "earliest_benefits_start_date": "2024-12-01", "offboard_on": "2024-12-01T00:00:00Z", "bank_account": null, "metadata": {}, "object": "string" } ``` **SDK Code** ```python import requests url = "https://test.api.kota.io/employees" payload = { "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "first_name": "string", "last_name": "string", "date_of_birth": "2024-12-01", "sex_at_birth": "male", "home_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" }, "national_tax_id": "string", "start_on": "2024-12-01", "email": "string" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://test.api.kota.io/employees'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"employer_id":"er_3b1333d87d9d4fd6ad83ba7f6b0e951a","first_name":"string","last_name":"string","date_of_birth":"2024-12-01","sex_at_birth":"male","home_address":{"line1":"string","city":"string","postal_code":"string","country_code":"af"},"national_tax_id":"string","start_on":"2024-12-01","email":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://test.api.kota.io/employees" payload := strings.NewReader("{\n \"employer_id\": \"er_3b1333d87d9d4fd6ad83ba7f6b0e951a\",\n \"first_name\": \"string\",\n \"last_name\": \"string\",\n \"date_of_birth\": \"2024-12-01\",\n \"sex_at_birth\": \"male\",\n \"home_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"national_tax_id\": \"string\",\n \"start_on\": \"2024-12-01\",\n \"email\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://test.api.kota.io/employees") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"employer_id\": \"er_3b1333d87d9d4fd6ad83ba7f6b0e951a\",\n \"first_name\": \"string\",\n \"last_name\": \"string\",\n \"date_of_birth\": \"2024-12-01\",\n \"sex_at_birth\": \"male\",\n \"home_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"national_tax_id\": \"string\",\n \"start_on\": \"2024-12-01\",\n \"email\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://test.api.kota.io/employees") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"employer_id\": \"er_3b1333d87d9d4fd6ad83ba7f6b0e951a\",\n \"first_name\": \"string\",\n \"last_name\": \"string\",\n \"date_of_birth\": \"2024-12-01\",\n \"sex_at_birth\": \"male\",\n \"home_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"national_tax_id\": \"string\",\n \"start_on\": \"2024-12-01\",\n \"email\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://test.api.kota.io/employees', [ 'body' => '{ "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "first_name": "string", "last_name": "string", "date_of_birth": "2024-12-01", "sex_at_birth": "male", "home_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" }, "national_tax_id": "string", "start_on": "2024-12-01", "email": "string" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://test.api.kota.io/employees"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"employer_id\": \"er_3b1333d87d9d4fd6ad83ba7f6b0e951a\",\n \"first_name\": \"string\",\n \"last_name\": \"string\",\n \"date_of_birth\": \"2024-12-01\",\n \"sex_at_birth\": \"male\",\n \"home_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"national_tax_id\": \"string\",\n \"start_on\": \"2024-12-01\",\n \"email\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "first_name": "string", "last_name": "string", "date_of_birth": "2024-12-01", "sex_at_birth": "male", "home_address": [ "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" ], "national_tax_id": "string", "start_on": "2024-12-01", "email": "string" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.kota.io/employees")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```