Sign in
Groups

Add an employee to a group

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

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

X-Platform-Idstring

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.

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

Changed in 2 of the 9 revisions of this API.11

  • c7d3d87193301See the full diff
    • ●

      added the new rejected enum value to the enrolment_status/allOf[EnrolmentStatus]/ response property for the response status 200

      response-property-enum-value-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 7b8b3ed87c961See the full diff
    • ○

      added the new optional header request parameter X-Platform-Id

      new-optional-request-parameter

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog