Sign in
Enrolment Intents

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.

post/enrolment_intents

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

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

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

status'processing' | 'scheduled' | 'action_required' | 'coverage_options_required' | 'pending_confirmation' | 'enrolling' | 'enrolled' | 'not_undertaken' | 'ineligible' | 'rejected' required
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.

objectstring

Object type identifier.

Changes

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

  • c7d3d871933011See the full diff
    • ●

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

      response-property-enum-value-added

    • ○

      added the non-success response with the status 409

      response-non-success-status-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