Employee Flow

Assign Employee to a Group

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.

Before starting, ensure you’ve completed:

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.

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.

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

Request body:

FieldTypeRequiredDescription
employee_idstringYesThe employee to check eligibility for, prefixed ee_.
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:

1{
2  "object": "eligibility_check",
3  "eligibility_status": "eligible",
4  "reasons": [],
5  "provider": {
6    "id": "pr_allianz",
7    "name": "Allianz"
8  },
9  "plan": {
10    "id": "pl_xyz789",
11    "name": "Health Plan Level 2",
12    "description": "Health insurance plan for employees"
13  }
14}

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.

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

Request body:

FieldTypeRequiredDescription
employee_idstringYesThe employee to add to the group, prefixed ee_.
create_enrolment_intentsbooleanNoWhether 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_configurationobjectNoEmployee-level policy preferences. Leave null to use group defaults.
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:

FieldDescription
desired_policy_start_dateThe employee’s preferred future policy start date. Use this to request future coverage only, not to backdate coverage. The provider may adjust it.
enrolment_dateThe date the employee agreed to enrol. If omitted, it defaults to employee start date or earliest benefit start date.

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.

1{
2  "object": "group_employee",
3  "id": "ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e",
4  "group_id": "gr_a1b2c3d4e5f60718293a4b5c6d7e8f90",
5  "eligibility_status": "eligible",
6  "desired_policy_start_date": "2026-07-01",
7  "enrolment_date": "2026-06-30",
8  "policies": [],
9  "enrolments": []
10}

Use these fields to decide what to show next:

FieldMeaning
eligibility_statuspending, 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:

EventFired when
group.employee.addedThe employee was successfully added to the group.
group.employee.eligibleAn employee in the group that was previously ineligible is now eligible.
enrolment_intent.processingAn 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

cURL
$curl -X GET "https://api.kota.io/groups/gr_a1b2c3d4e5f60718293a4b5c6d7e8f90/employees?employee_id=ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e" \
>  -H "Authorization: Bearer YOUR_API_KEY"

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.

SituationWhat to do
You receive an enrolment_intent.processing webhook or a later GET returns an ei_ ID in enrolments[]Continue with the 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 eligibleResolve the underlying employee or eligibility data, then wait for eligibility to update before creating a new intent.
The group has no active group policy yetFinish 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