> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/api/employee-flow/assign-employee-to-group/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server. # Assign Employee to a Group > Add an employee to a benefit group and start the enrolment flow when needed This guide walks you through assigning an existing employee to a benefit group. This is the step that makes an employee eligible to join a group policy and, depending on your configuration, can also start the employee enrolment flow. > **Info** > > Before starting, ensure you've completed: > > * [Authentication](/core-components/authentication): API key setup and idempotency > * [Employer and employee management](/core-components/employer-employee-management): syncing employers and employees > * [Employer Health Insurance Setup](/api/employer-health-insurance): creating or retrieving the target group > > The employee must belong to the same employer as the group. --- ## Overview A **group** represents the benefit the employee can join. For health insurance, the group usually maps to one selected plan or a bundle of benefits that must be managed together. Adding an employee to the group creates the employee's membership in that benefit group. If the group already has an active group policy, Kota can also create an **enrolment intent** for the employee. The enrolment intent handles the employee-facing part of the journey: eligibility checks, required information, disclosures, confirmation, and policy issuance. ```mermaid flowchart TD employee_exists[Employee exists] pre_check[Run eligibility pre-check] eligible{Eligible?} show_reason[Show ineligibility reason] add_to_group[Add employee to group] create_intent{Create enrolment intent?} manual_later[Create manually later if needed] enrolment_flow[Employee enrolment flow] employee_exists --> pre_check pre_check --> eligible eligible -- No --> show_reason eligible -- Yes --> add_to_group add_to_group --> create_intent create_intent -- No --> manual_later create_intent -- Yes --> enrolment_flow ``` > **Note** > > For API-only integrations, decide explicitly whether adding the employee should create > enrolment intents. The `create_enrolment_intents` default differs by integration type: > it defaults to `true` for hosted integrations and `false` for non-hosted integrations. --- ## Step 1: Check eligibility before assignment First, choose the group that represents the benefit the employee should receive. The group should belong to the same employer as the employee. For most health insurance flows, the group comes from one of these paths: * **Standard setup:** you created the group while building the employer benefit flow, then activated a group policy for it. * **Pre-created setup:** Kota created the groups and policies for you, and your platform retrieves the available groups before assigning employees. * **Migration:** Kota created groups during migration, and your platform maps employees to the correct migrated group. > **Warning** > > Archived groups cannot accept new employees. If the group has no group policy yet, the > employee can be added, but no enrolment intent is created until a policy exists. Before adding the employee, call the eligibility pre-check endpoint. This is a dry run: it checks whether the employee qualifies for the group without adding them to the group, creating an enrolment intent, or enrolling them. **Endpoint:** [`POST /groups/{group_id}/eligibility_check`](/api-reference/groups/check-employee-eligibility-for-a-group) **Request body:** | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------ | | `employee_id` | string | Yes | The employee to check eligibility for, prefixed `ee_`. | **`cURL`** ```bash cURL curl -X POST "https://api.kota.io/groups/gr_a1b2c3d4e5f60718293a4b5c6d7e8f90/eligibility_check" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "employee_id": "ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e" }' ``` **Response:** ```json { "object": "eligibility_check", "eligibility_status": "eligible", "reasons": [], "provider": { "id": "pr_allianz", "name": "Allianz" }, "plan": { "id": "pl_xyz789", "name": "Health Plan Level 2", "description": "Health insurance plan for employees" } } ``` If `eligibility_status` is `ineligible`, do not add the employee to the group yet. Show the human-readable `reasons[].message`, resolve the underlying employee or group data, then run the pre-check again. > **Warning** > > If you add an ineligible employee to the group and ask Kota to create enrolment intents, > the intent may still be created and then move to `ineligible`. Prefer resolving > eligibility first so the employee does not enter a flow they cannot complete. --- ## Step 2: Add the employee to the group Call `POST /groups/{group_id}/employees` with the employee ID. Send an `Idempotency-Key` so retries do not create duplicate work. **Endpoint:** [`POST /groups/{group_id}/employees`](/api-reference/groups/add-an-employee-to-a-group) **Request body:** | Field | Type | Required | Description | | -------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `employee_id` | string | Yes | The employee to add to the group, prefixed `ee_`. | | `create_enrolment_intents` | boolean | No | Whether Kota should create enrolment intents automatically when possible. This is legacy and the preference is to call the endpoint directly unless you have a hosted integration. | | `policy_configuration` | object | No | Employee-level policy preferences. Leave null to use group defaults. | **`cURL`** ```bash cURL curl -X POST "https://api.kota.io/groups/gr_a1b2c3d4e5f60718293a4b5c6d7e8f90/employees" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9a0f1b2c-3d4e-5f60-8a1b-2c3d4e5f6071" \ -d '{ "employee_id": "ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e", "create_enrolment_intents": true, "policy_configuration": { "desired_policy_start_date": "2026-07-01", "enrolment_date": "2026-06-30" } }' ``` Use `policy_configuration` only when this employee should differ from the group defaults: | Field | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `desired_policy_start_date` | The employee's preferred future policy start date. Use this to request future coverage only, not to backdate coverage. The provider may adjust it. | | `enrolment_date` | The date the employee agreed to enrol. If omitted, it defaults to employee start date or earliest benefit start date. | > **Info** > > If your product separates group assignment from employee opt-in, which is recommended, set > `create_enrolment_intents` to `false` and create the enrolment intent later, when the > employee starts the flow. --- ## Step 3: Handle the response The response represents the employee's membership in the group. ```json { "object": "group_employee", "id": "ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e", "group_id": "gr_a1b2c3d4e5f60718293a4b5c6d7e8f90", "eligibility_status": "eligible", "desired_policy_start_date": "2026-07-01", "enrolment_date": "2026-06-30", "policies": [], "enrolments": [] } ``` Use these fields to decide what to show next: | Field | Meaning | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eligibility_status` | `pending`, `eligible`, or `ineligible` for this employee in this group. | | `enrolments[]` | Enrolment intents associated with this group assignment. This is usually empty in the `POST` response, even when `create_enrolment_intents` is `true`, because intent creation can happen asynchronously. Fetch the group employee record later to reconcile created intents. | | `policies[]` | Policies already associated with this employee in this group. This is usually empty until enrolment completes. | If the API returns an error, check that: * the group exists and is not archived; * the employee exists and belongs to the same employer as the group; * the employee is not already assigned to the group; * the request body uses the correct identifiers. --- ## Step 4: Track assignment and eligibility Kota emits webhooks as group assignment and eligibility change: | Event | Fired when | | ----------------------------- | ---------------------------------------------------------------------------- | | `group.employee.added` | The employee was successfully added to the group. | | `group.employee.eligible` | An employee in the group that was previously `ineligible` is now `eligible`. | | `enrolment_intent.processing` | An enrolment intent was created and is being processed. | When you receive one of these events, fetch the group employee record to reconcile your state: **Endpoint:** [`GET /groups/{group_id}/employees`](/api-reference/groups/list-employees-in-a-group) **`cURL`** ```bash cURL curl -X GET "https://api.kota.io/groups/gr_a1b2c3d4e5f60718293a4b5c6d7e8f90/employees?employee_id=ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e" \ -H "Authorization: Bearer YOUR_API_KEY" ``` > **Note** > > Eligibility can change as employee data, provider rules, or group setup changes. Store > the group assignment separately from enrolment completion, and keep your UI driven by the > latest `eligibility_status`, `enrolments`, and `policies` values. --- ## Step 5: Start employee enrolment What happens next depends on whether an enrolment intent was created. | Situation | What to do | | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | You receive an `enrolment_intent.processing` webhook or a later `GET` returns an `ei_` ID in `enrolments[]` | Continue with the [Employee Enrolment](/api/employee-flow/employee-enrolment) guide and track that intent. | | No enrolment intent was created because `create_enrolment_intents` was `false` (recommended) | Create one when the employee is ready to enrol, ideally on the day they start the enrolment flow. | | No enrolment intent was created because the employee is not eligible | Resolve the underlying employee or eligibility data, then wait for eligibility to update before creating a new intent. | | The group has no active group policy yet | Finish group policy setup first, then create enrolment intents once the group is ready. | --- ## Best practices * **Use idempotency.** Always send an `Idempotency-Key` when adding an employee to a group. * **Pre-check eligibility first.** Use `POST /groups/{group_id}/eligibility_check` before assignment so you can show ineligibility reasons without adding the employee to the group. * **Separate assignment from enrolment.** Adding an employee to a group makes them part of the benefit group; it does not always mean the employee has completed enrolment. * **React to webhooks.** Use `group.employee.added`, `group.employee.eligible`, and enrolment-intent events to drive your UI instead of assuming work is complete immediately after the `POST`. * **Store the returned IDs.** Persist the `group_id`, `employee_id`, and any returned enrolment intent IDs so you can reconcile later. --- ## Next steps * [Employee Enrolment](/api/employee-flow/employee-enrolment): complete the employee-facing enrolment flow * [Webhooks and events](/core-components/webhooks-and-events): receive assignment and enrolment updates * [API Errors](/api-reference/errors): handle validation and not-found responses > Add an employee to a benefit group and start the enrolment flow when needed