Groups

Add an employee to a group

Changed on

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.

post/groups/{group_id}/employees

Request

  • Base URL
    https://test.api.kota.io
  • URL
    https://test.api.kota.io/groups/{group_id}/employees
  • Auth
    HTTP bearer

Path parameters

group_idstring required
Example:gr_3b1333d87d9d4fd6ad83ba7f6b0e951a

Headers

Idempotency-Keystring

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

Request body

employee_idstring required

Employee Id

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

Example request

{
  "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "policy_configuration": {
    "desired_policy_start_date": "2024-12-01",
    "enrolment_date": "2024-12-01"
  }
}

Response

OK

objectstring

The object type

idstring required

Unique identifier for the employee.

group_idstring required

Unique identifier for the group.

desired_policy_start_datestring date 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_datestring date 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.

eligibility_status'pending' | 'eligible' | 'ineligible' required
enrolment_status'enrolled' | 'enrolling' | 'opted_out' | 'cancelled' | 'enrolment_available' | 'not_available' | 'rejected' required

Example response

{
  "id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "group_id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "policies": [
    {
      "id": "p_3b1333d87d9d4fd6ad83ba7f6b0e951a"
    }
  ],
  "enrolments": [
    {
      "id": "ei_3b1333d87d9d4fd6ad83ba7f6b0e951a"
    }
  ],
  "desired_policy_start_date": "2024-12-01",
  "enrolment_date": "2024-12-01",
  "scheduled_group_transitions": [
    {
      "new_group_id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a",
      "scheduled_date": "2024-12-01"
    }
  ]
}

Changes

  • 998f7cb004abRevision changes
    • warning

      deleted the header request parameter X-Platform-Id

  • c7d3d8719330Revision changes
    • warning

      added the new rejected enum value to the //// response property for the response status