> 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 a group POST https://test.api.kota.io/groups Content-Type: application/json Creates a `group` for the specified `employer`. Reference: https://docs.kota.io/api-reference/groups/create-group ## 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 - `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 CreateGroupRequest. - `employer_id` (string, required) — Identifier of the `employer` to create the group for. Prefixed with `er_`. - `name` (string, required) — Human-readable name of the `group`. - `description` (string, optional, nullable) — Short description of the purpose or scope of the `group`. ## Response ### 200 OK - `id` (string, required) — Unique identifier for the `group`. Prefixed with `gr_`. - `name` (string, required) — Human-readable name of the `group`. - `status` (enum, required) — Current lifecycle state of the `group`, indicating its current progress. Possible values are: - `pending`: Group is being configured, may require a `quote_intent` or a `setup_intent` to be ready. - `ready`: Setup is complete, regardless of policy start dates employees could start enrolling into policies. - `archived`: Archived as the group is no longer active or in use for any reason. Employees can no longer be added to the group. - Allowed values: `pending`, `ready`, `archived` - `group_type` (enum, required) — Indicates how policies are organized for this group. - `single`: exactly one policy is associated to the group. - `bundled`: multiple policies are bundled under the group. - `undefined`: type not yet determined or not applicable. - Allowed values: `undefined`, `single`, `bundled` - `enrolment_type` (enum, required) — Indicates how employees are enrolled into the group. - `manual`: employees must be enrolled through an API. - `automatic`: employees are enrolled automatically upon being created with the Employer. - Allowed values: `manual`, `automatic` - `employer_id` (string, required) — Identifier for the `employer` that owns this `group`. Prefixed with `er_`. - `group_policy_ids` (list of string, required) — Group policy unique identifiers associated with this group. - `group_quote_intent_ids` (list of string, required) — Group quote intent unique identifiers associated with this group. - `group_policy_intent_ids` (list of string, required) — Group policy intent unique identifiers associated with this group. - `description` (string, optional, nullable) — Short description of the purpose or scope of the `group`. - `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) ### 404 Not Found Error Not Found - `type` (string, optional, nullable) - `title` (string, optional, nullable) - `status` (integer, optional, nullable) - `detail` (string, optional, nullable) - `instance` (string, optional, nullable) ## Examples **Request** ```json { "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "name": "string" } ``` **Response** ```json { "id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a", "name": "string", "status": "pending", "group_type": "undefined", "enrolment_type": "manual", "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "group_policy_ids": [ "gp_3b1333d87d9d4fd6ad83ba7f6b0e951a" ], "group_quote_intent_ids": [ "gqi_3b1333d87d9d4fd6ad83ba7f6b0e951a" ], "group_policy_intent_ids": [ "gpi_3b1333d87d9d4fd6ad83ba7f6b0e951a" ], "description": null, "object": "string" } ``` **SDK Code** ```python import requests url = "https://test.api.kota.io/groups" payload = { "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "name": "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/groups'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"employer_id":"er_3b1333d87d9d4fd6ad83ba7f6b0e951a","name":"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/groups" payload := strings.NewReader("{\n \"employer_id\": \"er_3b1333d87d9d4fd6ad83ba7f6b0e951a\",\n \"name\": \"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/groups") 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 \"name\": \"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/groups") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"employer_id\": \"er_3b1333d87d9d4fd6ad83ba7f6b0e951a\",\n \"name\": \"string\"\n}") .asString(); ``` ```php request('POST', 'https://test.api.kota.io/groups', [ 'body' => '{ "employer_id": "er_3b1333d87d9d4fd6ad83ba7f6b0e951a", "name": "string" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://test.api.kota.io/groups"); 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 \"name\": \"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", "name": "string" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.kota.io/groups")! 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() ```