> 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.

# Add an employee to a group

POST https://test.api.kota.io/groups/{group_id}/employees
Content-Type: application/json

Adds an existing employee to a `group`. The employee must belong to the same employer as the `group`. If there is a `group_policy` associated with the `group`, a corresponding `enrolment_intent` will be created for the employee.

Reference: https://docs.kota.io/api-reference/groups/add-employee-to-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

### Path parameters

- `group_id` (string, required)

### 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 an AddEmployeeToGroupRequest.

- `employee_id` (string, required) — Employee Id
- `create_enrolment_intents` (boolean, optional, nullable) — Controls whether enrolment intents are automatically created for the employee. Defaults to `true` for hosted platforms. When `true` on a hosted platform, the response includes an `enrolment_intent_id`. For non-hosted platforms, the `enrolment_intent_id` is not included in the response, subscribe to the `enrolment_intent.processing` webhook to be notified when the enrolment intent is created.
- `policy_configuration` (PolicyConfigurationRequest, optional) — Policy configuration for the employee in this group. Leave null to use `group` defaults.

## Response

### 200

OK

- `id` (string, required) — Unique identifier for the employee.
- `group_id` (string, required) — Unique identifier for the group.
- `policies` (list of PolicyReference, required) — List of policies associated with the employee in this group.
- `enrolments` (list of EnrolmentReference, required) — List of enrolments associated with the employee in this group.
- `eligibility_status` (enum, required) — Eligibility status for the employee in this group. `Pending` = no eligibility check performed (no group policy), `Eligible` = employee meets provider's eligibility criteria, `Ineligible` = employee does not meet eligibility criteria (e.g., age restrictions).
  - Allowed values: `pending`, `eligible`, `ineligible`
- `enrolment_status` (enum, required) — Enrolment status for the employee in this group. Derived from policy and enrolment intent statuses.
  - Allowed values: `enrolled`, `enrolling`, `opted_out`, `cancelled`, `enrolment_available`, `not_available`, `rejected`
- `scheduled_group_transitions` (list of ScheduledGroupTransitionResponse, required) — List of scheduled group transitions for the employee. Only includes pending transitions.
- `object` (string, optional) — The object type
- `desired_policy_start_date` (date, optional, nullable) — The desired date for the employee's policy to start. This date is not guaranteed to be honored by the insurance provider and may be adjusted based on provider-specific rules and requirements.
- `enrolment_date` (date, optional, nullable) — The date on which the employee agreed to enrol into the group's policies. This date may be used by some insurance providers to determine the policy start date.

## 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)

### 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)

## Types

### PolicyConfigurationRequest

- `desired_policy_start_date` (date, optional, nullable) — The desired date for the employee's policy to start. This date is not guaranteed to be honored by the insurance provider and may be adjusted based on provider-specific rules and requirements. If unspecified, the policy start date will be determined by the insurance provider.
- `enrolment_date` (date, optional, nullable) — The date on which the employee agreed to enrol into the group's policies. This date may be used by some insurance providers to determine the policy start date. If unspecified, the enrolment date will default to the date the enrolment intent is processed.

### PolicyReference

- `id` (string, required) — Unique identifier for the policy.

### EnrolmentReference

- `id` (string, required) — Unique identifier for the enrolment.

### ScheduledGroupTransitionResponse

- `new_group_id` (string, required) — Unique identifier for the group the employee will be moved to
- `scheduled_date` (date, required) — The date when the employee will be moved to the new group

## Examples

**Request**

```json
{
  "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a"
}
```

**Response**

```json
{
  "id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "group_id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "policies": [
    {
      "id": "p_3b1333d87d9d4fd6ad83ba7f6b0e951a"
    }
  ],
  "enrolments": [
    {
      "id": "ei_3b1333d87d9d4fd6ad83ba7f6b0e951a"
    }
  ],
  "eligibility_status": "pending",
  "enrolment_status": "enrolled",
  "scheduled_group_transitions": [
    {
      "new_group_id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a",
      "scheduled_date": "2024-12-01"
    }
  ],
  "object": "string",
  "desired_policy_start_date": "2024-12-01",
  "enrolment_date": "2024-12-01"
}
```

**SDK Code**

```python
import requests

url = "https://test.api.kota.io/groups/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/employees"

payload = { "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a" }
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://test.api.kota.io/groups/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/employees';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <apiKey>', 'Content-Type': 'application/json'},
  body: '{"employee_id":"ee_3b1333d87d9d4fd6ad83ba7f6b0e951a"}'
};

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/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/employees"

	payload := strings.NewReader("{\n  \"employee_id\": \"ee_3b1333d87d9d4fd6ad83ba7f6b0e951a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <apiKey>")
	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/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/employees")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"employee_id\": \"ee_3b1333d87d9d4fd6ad83ba7f6b0e951a\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://test.api.kota.io/groups/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/employees")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employee_id\": \"ee_3b1333d87d9d4fd6ad83ba7f6b0e951a\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://test.api.kota.io/groups/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/employees', [
  'body' => '{
  "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a"
}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://test.api.kota.io/groups/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/employees");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"employee_id\": \"ee_3b1333d87d9d4fd6ad83ba7f6b0e951a\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.kota.io/groups/gr_3b1333d87d9d4fd6ad83ba7f6b0e951a/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()
```