> 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 employer POST https://test.api.kota.io/employers Content-Type: application/json Creates an `employer`. Reference: https://docs.kota.io/api-reference/employers/create-employer ## 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 CreateEmployerRequest. - `legal_name` (string, required) — Legal name of the company. NOTE: This field will be normalized according to our internal formatting rules. - `legal_address` (AddressModel, required) - `contact` (ContactModel, required) - `registration_number` (string, optional, nullable) — Company registration number. NOTE: This field will be normalized according to our internal formatting rules. - `earliest_benefits_start_date` (date, optional, nullable) — The earliest date this employer is permitted to set up any benefits scheme. If this date is in the future, benefit setup will be blocked until then. Used to delay scheme setup access (e.g., for onboarding alignment). **Constraints:** - Can only be set or updated if no group policy or group quote exists. - Must be a valid date in the future. - `applicable_collective_agreement` (string, optional, nullable) — Name of the collective agreement that applies to the employer's workforce, if any. NOTE: This field will be normalized according to our internal formatting rules. - `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 - `id` (string, required) - `legal_name` (string, required) - `legal_address` (AddressModel, required) - `contact` (ContactModel, required) - `platform_id` (string, optional) - `status` (enum, optional) - Allowed values: `pending`, `active`, `offboarding`, `inactive`, `restricted` - `registration_number` (string, optional, nullable) - `offboard_on` (datetime, optional, nullable) - `earliest_benefits_start_date` (date, optional, nullable) - `applicable_collective_agreement` (string, optional, nullable) — Name of the collective agreement that applies to the employer's workforce, if any. - `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. ### ContactModel - `name` (string, required) — Contact person name. NOTE: This field will be normalized according to our internal formatting rules. - `email` (string, required) — Contact email address. NOTE: This field will be normalized according to our internal formatting rules. ## Examples **Request** ```json { "legal_name": "string", "legal_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" }, "contact": { "name": "string", "email": "string" } } ``` **Response** ```json { "id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "legal_name": "string", "legal_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af", "line2": null, "line3": null, "state": null }, "contact": { "name": "string", "email": "string" }, "platform_id": "pt_3b1333d87d9d4fd6ad83ba7f6b0e951a", "status": "pending", "registration_number": null, "offboard_on": "2024-12-01T00:00:00Z", "earliest_benefits_start_date": "2024-12-01", "applicable_collective_agreement": null, "metadata": {}, "object": "string" } ``` **SDK Code** ```python import requests url = "https://test.api.kota.io/employers" payload = { "legal_name": "string", "legal_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" }, "contact": { "name": "string", "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/employers'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"legal_name":"string","legal_address":{"line1":"string","city":"string","postal_code":"string","country_code":"af"},"contact":{"name":"string","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/employers" payload := strings.NewReader("{\n \"legal_name\": \"string\",\n \"legal_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"contact\": {\n \"name\": \"string\",\n \"email\": \"string\"\n }\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/employers") 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 \"legal_name\": \"string\",\n \"legal_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"contact\": {\n \"name\": \"string\",\n \"email\": \"string\"\n }\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/employers") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"legal_name\": \"string\",\n \"legal_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"contact\": {\n \"name\": \"string\",\n \"email\": \"string\"\n }\n}") .asString(); ``` ```php request('POST', 'https://test.api.kota.io/employers', [ 'body' => '{ "legal_name": "string", "legal_address": { "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" }, "contact": { "name": "string", "email": "string" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://test.api.kota.io/employers"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"legal_name\": \"string\",\n \"legal_address\": {\n \"line1\": \"string\",\n \"city\": \"string\",\n \"postal_code\": \"string\",\n \"country_code\": \"af\"\n },\n \"contact\": {\n \"name\": \"string\",\n \"email\": \"string\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "legal_name": "string", "legal_address": [ "line1": "string", "city": "string", "postal_code": "string", "country_code": "af" ], "contact": [ "name": "string", "email": "string" ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.kota.io/employers")! 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() ```