--- title: "Create a new enrolment intent" method: POST path: "/enrolment_intents" tags: ["Enrolment Intents"] --- # Create a new enrolment intent `POST /enrolment_intents` 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. ## Headers - `Idempotency-Key` string - `X-Platform-Id` string ## Request body - CreateEnrolmentIntentRequest - `employee_id` string, required — Identifier for the employee associated with this enrolment intent. Prefixed with `ee_`. - `group_id` string, required — Identifier for the group associated with this enrolment intent. Prefixed with `gr_`. - `policy_configuration` PolicyConfigurationRequest - `desired_policy_start_date` string, 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. If unspecified, the policy start date will be determined by the insurance provider. - `enrolment_date` string, 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. If unspecified, the enrolment date will default to the date the enrolment intent is processed. - `force_confirmation` boolean, 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. - `coverage_selections` PlanCoverageOptionSelectionRequest[], nullable — Optional plan coverage option selections for policy-scoped configurations. If provided and valid, the coverage_options_required step will be skipped. - `configuration_id` string, required — Configuration ID (prefixed with `pc_`). - `options` SelectedOptionRequest[], required — Selected options with optional sub-options. - `option_id` string, required — Option ID (prefixed with `pco_`). - `sub_options` SelectedOptionRequest[], nullable — Sub-option selections, if applicable. ## Response `200` OK - EnrolmentIntentResponse - `id` string, required — Unique identifier for the enrolment intent. Prefixed with `ei_`. - `employee_id` string, required — Identifier for the employee associated with this enrolment intent. Prefixed with `ee_`. - `group_id` string, 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_confirmation` boolean, 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. - `policy_enrolments` EnrolmentIntentPolicyEnrolmentResponse[], required — Policy enrolment information - `type` 'health_insurance' | 'life_assurance', required - `estimated_effective_from` string, date, required — Estimated date when the policy of this type is expected to become effective in ISO 8601 (YYYY-MM-DD). - `provider` PolicyProviderResponse, required - `id` string, required — Unique identifier for the provider. Prefixed with pr_. - `name` string, required — Provider display name. - `description` string, required — Short description of the provider. - `logo_url` string, required - `employer_portal_url` string, nullable — URL for the employer portal. - `employee_portal_url` string, nullable — URL for the employee portal (may include claims management). - `support_phone_number` string, nullable — Provider support phone number in E.164 format. - `plan` PolicyPlanResponse, required - `id` string, required — Unique identifier for the plan. Prefixed with pl_. - `name` string, required — Plan display name. - `description` string, required — Short description of the plan. - `currency` 'eur' | 'aed' | 'afn' | 'xcd' | 'all' | 'amd' | 'aoa' | 'ars' | 'usd' | 'aud' | 'awg' | 'azn' | 'bam' | 'bbd' | 'bdt' | 'xof' | 'bgn' | 'bhd' | 'bif' | 'bmd' | 'bnd' | 'bob' | 'bov' | 'brl' | 'bsd' | 'inr' | 'btn' | 'nok' | 'bwp' | 'byn' | 'bzd' | 'cad' | 'xaf' | 'cdf' | 'chf' | 'che' | 'chw' | 'nzd' | 'clp' | 'clf' | 'cny' | 'cop' | 'cou' | 'crc' | 'cup' | 'cuc' | 'cve' | 'ang' | 'czk' | 'djf' | 'dkk' | 'dop' | 'dzd' | 'egp' | 'mad' | 'ern' | 'etb' | 'fjd' | 'fkp' | 'mdl' | 'gbp' | 'gel' | 'ghs' | 'gip' | 'gmd' | 'gnf' | 'gtq' | 'gyd' | 'hkd' | 'hnl' | 'hrk' | 'htg' | 'huf' | 'idr' | 'xdr' | 'ils' | 'iqd' | 'irr' | 'isk' | 'jmd' | 'jod' | 'jpy' | 'kes' | 'kgs' | 'khr' | 'kmf' | 'kpw' | 'krw' | 'kwd' | 'kyd' | 'kzt' | 'lak' | 'lbp' | 'lkr' | 'lrd' | 'lsl' | 'zar' | 'lyd' | 'mga' | 'mkd' | 'mmk' | 'mnt' | 'mop' | 'mru' | 'mur' | 'mvr' | 'mwk' | 'mxn' | 'mxv' | 'myr' | 'mzn' | 'nad' | 'xpf' | 'ngn' | 'nio' | 'npr' | 'omr' | 'pab' | 'pen' | 'pgk' | 'php' | 'pkr' | 'pln' | 'pyg' | 'qar' | 'ron' | 'rsd' | 'rub' | 'rwf' | 'sar' | 'sbd' | 'scr' | 'sdg' | 'sek' | 'sgd' | 'shp' | 'sll' | 'sos' | 'srd' | 'ssp' | 'stn' | 'svc' | 'xsu' | 'syp' | 'twd' | 'szl' | 'thb' | 'tjs' | 'tmt' | 'tnd' | 'top' | 'try' | 'ttd' | 'tzs' | 'uah' | 'ugx' | 'usn' | 'uyu' | 'uyi' | 'uyw' | 'uzs' | 'ves' | 'vnd' | 'vuv' | 'wst' | 'yer' | 'xua' | 'zmw' | 'zwl', required - `documents` PlanDocumentResponse[], required — List of plan documents (e.g., IPIDs, T&Cs). - `type` 'ipid' | 'table_of_cover' | 'waiting_periods' | 'hospital_list' | 'plan_summary' | 'terms_and_conditions' | 'other' - `title` string, required — Title of the document. - `link` string, required — Public URL to the document. This could be any format (PDF, HTML, etc.). - `health_insurance` HealthInsuranceEnrolmentIntentResponse - `configuration` HealthInsurancePolicyConfigurationResponse, required - `cost_sharing` HealthInsuranceCostSharingConfigurationResponse, required - `type` 'member_count' | 'member_selection' | 'percentage' | 'policyholder_only' | 'family_type', required - `member_count` HealthInsuranceMemberCountCostSharingConfigurationResponse - `adults` integer, required — Number of additional adults covered, including partner/spouse. - `children` integer, required — Number of additional children covered. - `member_selection` HealthInsuranceMemberSelectionCostSharingConfigurationResponse - `partner` boolean, required — If a spouse/partner is covered. - `children` boolean, required — If children are covered. - `percentage` HealthInsurancePercentageCostSharingConfigurationResponse - `percentage` integer, required — Employer coverage percentage: For 40% send 40. For 100% send 100. - `family_type` HealthInsuranceFamilyTypeCostSharingConfigurationResponse - `type` 'single' | 'couple' | 'single_with_children' | 'family', required - `coverage_options` PlanCoverageResponse[], nullable — Available plan coverage options at the policy scope. Only present when the plan has policy-scoped coverage configurations. - `id` string, required — Unique identifier for the coverage selection. Prefixed with `pc_`. - `name` string, required — Title for this coverage selection. Typically used as the display heading. - `description` string, nullable — Full description of this coverage selection. - `scope` 'group_policy' | 'policy' | 'member', required - `input_type` 'single_select' | 'multi_select', required - `required` boolean, required — Whether a selection is mandatory. - `min_selections` integer, nullable — Minimum required selections (multi-select only). - `max_selections` integer, nullable — Maximum allowed selections (multi-select only). - `sort_order` integer, nullable — Display ordering hint. - `group_label` string, nullable — Optional grouping label for UI rendering. Indicates which coverage selections are best presented together from a UX standpoint. - `options` PlanCoverageOptionResponse[], required — Available options within this coverage selection. - `id` string, required — Unique identifier for this coverage option. Prefixed with `pco_`. - `name` string, required — Display name for this coverage option. - `description` string, nullable — Longer explanation of this coverage option. - `learn_more_url` string, nullable — Link to learn more about this coverage option. - `from_price` number, double, nullable — Lowest applicable monthly price for this coverage option. - `benefits` PlanCoverageOptionBenefitResponse[], nullable — Benefit items included with this coverage option. - `name` string, required — Benefit name. - `description` string, nullable — Benefit description. - `sub_options` PlanCoverageOptionResponse[], nullable — Nested sub-options available when this option is selected. - `eligibility_criteria` EmployerEligibilityCriterionResponse[], nullable — Eligibility criteria that must be met to select this coverage option. - `type` 'employees_count' | 'members_count' | 'industry_exclusions', required - `description` string, required — Human-readable description of the criterion. - `employees_count` EmployeesCountDetails - … - `members_count` MembersCountDetails - … - `industry_exclusions` IndustryExclusionsDetails - … - `coverage_selections` PlanCoverageOptionSelectionResponse[], nullable — Current coverage option selections. Populated when selections have been submitted. - `configuration_id` string, required — Configuration ID (prefixed with `pc_`). - `options` SelectedOptionResponse[], required — Selected options. - `option_id` string, required — Option ID (prefixed with `pco_`). - `sub_options` SelectedOptionResponse[], nullable — Selected sub-options, if applicable. - `id` string, nullable — Unique identifier for the policy created as part of this enrolment intent. Prefixed with `p_`. Only populated once the policy has been created. - `object` string — Object type identifier. - `ineligibility_reason` EnrolmentIntentInelgibilityReason - `code` 'employee_restricted' | 'employee_under_minimum_age' | 'employee_above_maximum_age' | 'employee_not_active' | 'employment_not_started' | 'unknown', required - `reason` string, required — A reason that can be displayed to the end user explaining why the enrolment intent is ineligible. - `policy_configuration` PolicyConfigurationResponse - `desired_policy_start_date` string, date, nullable — Desired policy start date, not guaranteed to be honoured by the provider. - `enrolment_date` string, date, nullable — The date on which the employee has agreed to enrol into a the group policy. This date may be used by some providers to determine policy start date. - `action_required` EnrolmentIntentActionRequiredResponse - `code` 'provide_dependant_information' | 'provide_beneficiary_information' | 'provide_missing_information', required - `reason` string, required — Brief reason for the required action. - `reason_description` string, required — Detailed description of the required action. - `due_by` string, date-time, required — The deadline by which the action must be completed. The day is included (i.e. the action can be completed any time during this day in the user's local time). - `pending_confirmation` EnrolmentIntentPendingConfirmationResponse - `due_by` string, date-time, required — The deadline by which the confirmation must be completed. - `code` 'confirm_enrolment', required - `reason` string, required — A reason for the confirmation action that needs to be taken. - `reason_description` string, required — A reason description explaining the confirmation action that needs to be taken. - `associated_persons` EnrolmentIntentAssociatedPersonResponse - `optional` boolean, required — Indicates whether providing information for the related type is optional. - `type` 'dependents', required - `dependent` EnrolmentIntentDependentResponse, required - `intent_id` string, required — Unique identifier for the dependents management intent. Prefixed with `dmi_`. - `status` 'processing' | 'confirmed', required - `disclosures` DisclosureResponse[], required — Disclosures associated with this intent. - `category` 'regulatory' | 'provider' | 'intermediary', required - `type` 'intermediary_role' | 'intermediary_commission' | 'underwriter_disclaimer' | 'anti_selection_notice' | 'statement_of_needs' | 'product_information' | 'pre_existing_conditions' | 'statutory_warning', required - `text` string, required — The disclosure statement text. ## Other responses - `400` — Bad Request - `404` — Not Found - `409` — Conflict --- [API](https://skmtc.net/kota/apis/kota-api.md) · [All operations](https://skmtc.net/kota/apis/kota-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kota/kota-api/revisions/85bb8b3c42b4/schema)