Create a new enrolment intent

Creates a new enrolment_intent to manage the enrolment of an employee into a group. An enrolment intent represents the intention to enrol an employee into a specific group, and tracks the status and progress of that enrolment process.

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

Identifier for the employee associated with this enrolment intent. Prefixed with ee_.

group_idstring required

Identifier for the group associated with this enrolment intent. Prefixed with gr_.

force_confirmationboolean required

If set to true, the system will always force the PendingConfirmation state before enrolling the employee, even if no action is required. This can be useful in scenarios where you want to ensure that the employee explicitly confirms their enrolment, regardless of their eligibility or any other factors. Defaults to false.

Example request

{
  "employee_id": "ee_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "group_id": "gr_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "policy_configuration": {
    "desired_policy_start_date": "2024-12-01",
    "enrolment_date": "2024-12-01"
  },
  "force_confirmation": true,
  "coverage_selections": [
    {
      "configuration_id": "pc_3b1333d87d9d4fd6ad83ba7f6b0e951a",
      "options": [
        {
          "option_id": "pco_3b1333d87d9d4fd6ad83ba7f6b0e951a"
        }
      ]
    }
  ]
}

Response

OK

idstring required

Unique identifier for the enrolment intent. Prefixed with ei_.