Kota Enrolment Intents API
The Enrolment Intents API from Kota — 7 operation(s) for enrolment intents.
The Enrolment Intents API from Kota — 7 operation(s) for enrolment intents.
openapi: 3.1.0
info:
title: API Reference Associated Persons Enrolment Intents API
version: 1.0.0
servers:
- url: https://test.api.kota.io
description: test
- url: https://api.kota.io
description: production
tags:
- name: Enrolment Intents
paths:
/enrolment_intents:
post:
tags:
- Enrolment Intents
summary: Create a new enrolment intent
description: 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.
operationId: CreateEnrolmentIntent
parameters:
- name: Idempotency-Key
in: header
description: 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](/api#idempotent-requests)
schema:
type: string
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CreateEnrolmentIntentRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
get:
tags:
- Enrolment Intents
summary: List all enrolment intents
description: Returns a list of `enrolment_intents`. The `enrolment_intents` are returned sorted by creation date, with the most recent `enrolment_intent` appearing first.
operationId: ListEnrolmentIntents
parameters:
- name: employee_id
in: query
description: Filters enrolment intents by employee.
schema:
pattern: ee_.+
type: string
description: Filters enrolment intents by employee.
example: ee_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: group_id
in: query
description: Filters enrolment intents by group.
schema:
pattern: gr_.+
type: string
description: Filters enrolment intents by group.
example: gr_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: status
in: query
description: 'Multiple values can be provided by separating them with a comma. Allowed values are: `processing`, `scheduled`, `action_required`, `addon_selection_required`, `pending_confirmation`, `enrolling`, `enrolled`, `not_undertaken`, `ineligible`.'
schema:
type: string
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
schema:
type: integer
description: The page of results to return. Defaults to 1 if not provided.
format: int32
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
schema:
type: integer
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponsePagedList'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}:
put:
tags:
- Enrolment Intents
summary: Update policy configuration enrolment intent
description: Updates the policy configuration for an existing `enrolment_intent`. This will reset the enrolment intent back to `processing` status and re-evaluate the enrolment intent based on the new configuration provided.Unavailable for enrolment intents that are already `enrolling` or `enrolled`.
operationId: UpdateEnrolmentIntentConfiguration
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
pattern: ei_.+
type: string
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PolicyConfigurationRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponse'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
get:
tags:
- Enrolment Intents
summary: Retrieve an enrolment intent
description: Retrieves an `enrolment_intent` object.
operationId: RetrieveEnrolmentIntent
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
pattern: ei_.+
type: string
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponse'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/requirements:
get:
tags:
- Enrolment Intents
summary: List requirements for an enrolment intent
description: Returns a paginated list of adaptive requirements for an `enrolment_intent`. Requirements must be fulfilled before enrolment can proceed.
operationId: ListEnrolmentIntentRequirements
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
pattern: ei_.+
type: string
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: object_type
in: query
description: Filter by object type (employee or employer)
schema:
allOf:
- $ref: '#/components/schemas/RequirementObjectTypeEnumParameter'
description: Filter by object type (employee or employer)
- name: object_id
in: query
description: Filter by object ID (employee ID or employer ID)
schema:
type: string
description: Filter by object ID (employee ID or employer ID)
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
schema:
type: integer
description: The page of results to return. Defaults to 1 if not provided.
format: int32
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
schema:
type: integer
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentRequirementResponsePagedList'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/confirm:
post:
tags:
- Enrolment Intents
summary: Confirm an enrolment intent
description: Confirms an `enrolment_intent` that is in `PendingConfirmation` status. This transitions the enrolment intent to `Enrolling` status and initiates the enrolment process with the insurance provider.
operationId: ConfirmEnrolmentIntent
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
pattern: ei_.+
type: string
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/reject:
post:
tags:
- Enrolment Intents
summary: Reject an enrolment intent
description: Rejects an `enrolment_intent` that is in `PendingConfirmation`, `ActionRequired`, or `AddonSelectionRequired` status. This transitions the enrolment intent to `NotUndertaken` status.
operationId: RejectEnrolmentIntent
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
pattern: ei_.+
type: string
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/coverage-selections:
post:
tags:
- Enrolment Intents
summary: Submit coverage selections for an enrolment intent
description: Submits plan coverage option selections for an enrolment intent in the `addon_selection_required` status.
operationId: SubmitEnrolmentIntentCoverageSelections
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
pattern: ei_.+
type: string
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SubmitCoverageSelectionsRequest'
required: true
responses:
'204':
description: No Content
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/create_dependents_management_intent:
post:
tags:
- Enrolment Intents
summary: Create a dependents management intent for an enrolment intent
description: Creates a dependents management intent as a sub-intent of an enrolment intent. The enrolment intent must be in `pending_confirmation` status.
operationId: CreateDependentsManagementIntentForEnrolmentIntent
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
pattern: ei_.+
type: string
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DependentsManagementIntentResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
PlanWithPricingResponse:
required:
- description
- id
- name
- pricing
type: object
properties:
id:
pattern: pl_.+
type: string
description: Unique identifier for the plan. Prefixed with `pl_`.
example: pl_3b1333d87d9d4fd6ad83ba7f6b0e951a
name:
type: string
description: The name of the plan.
description:
type: string
description: Description of the plan.
pricing:
allOf:
- $ref: '#/components/schemas/PlanPricingResponse'
description: Pricing information for the plan.
additionalProperties: false
PlanCoverageOptionInputType:
enum:
- single_select
- multi_select
type: string
PolicyType:
enum:
- health_insurance
- life_assurance
type: string
PlanCoverageOptionScope:
enum:
- group_policy
- policy
- member
type: string
RequirementType:
enum:
- group_quote_intent
- group_policy_intent
- dependent_management_intent
- policy_amendment_intent
- enrolment_intent
type: string
PlanCoverageResponse:
required:
- id
- input_type
- name
- options
- required
- scope
type: object
properties:
id:
pattern: pc_.+
type: string
description: Unique identifier for the coverage selection. Prefixed with `pc_`.
example: pc_3b1333d87d9d4fd6ad83ba7f6b0e951a
name:
type: string
description: Title for this coverage selection. Typically used as the display heading.
description:
type:
- 'null'
- string
description: Full description of this coverage selection.
scope:
allOf:
- $ref: '#/components/schemas/PlanCoverageOptionScope'
description: 'Scope of selection for this coverage selection: `group_policy` (employer selects for the group), `policy` (per-policy selection), or `member` (individual member selects).'
input_type:
allOf:
- $ref: '#/components/schemas/PlanCoverageOptionInputType'
description: Describes whether this input allows selecting a single option or multiple options.
required:
type: boolean
description: Whether a selection is mandatory.
example: true
min_selections:
type:
- 'null'
- integer
description: Minimum required selections (multi-select only).
format: int32
max_selections:
type:
- 'null'
- integer
description: Maximum allowed selections (multi-select only).
format: int32
sort_order:
type:
- 'null'
- integer
description: Display ordering hint.
format: int32
group_label:
type:
- 'null'
- string
description: Optional grouping label for UI rendering. Indicates which coverage selections are best presented together from a UX standpoint.
options:
type: array
items:
$ref: '#/components/schemas/PlanCoverageOptionResponse'
description: Available options within this coverage selection.
additionalProperties: false
HealthInsuranceFamilyTypeCostSharingConfigurationResponse:
required:
- type
type: object
properties:
type:
allOf:
- $ref: '#/components/schemas/HealthInsuranceFamilyCostSharingType'
description: Employer coverage family type
additionalProperties: false
PlanCoverageOptionSelectionRequest:
required:
- configuration_id
- options
type: object
properties:
configuration_id:
pattern: pc_.+
type: string
description: Configuration ID (prefixed with `pc_`).
example: pc_3b1333d87d9d4fd6ad83ba7f6b0e951a
options:
type: array
items:
$ref: '#/components/schemas/SelectedOptionRequest'
description: Selected options with optional sub-options.
additionalProperties: false
DependentsManagementIntentStatus:
enum:
- action_required
- processing
- completed
- not_undertaken
type: string
x-fern-enum:
action_required:
description: Dependents information needs to be provided.
processing:
description: Dependents are being validated and processed.
completed:
description: Dependents have been successfully processed and validated.
not_undertaken:
description: Dependents management intent has been aborted.
PolicyConfigurationResponse:
type: object
properties:
desired_policy_start_date:
type:
- 'null'
- string
description: Desired policy start date, not guaranteed to be honoured by the provider.
format: date
example: '2024-12-01'
enrolment_date:
type:
- 'null'
- string
description: 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.
format: date
example: '2024-12-01'
additionalProperties: false
HealthInsurancePolicyConfigurationResponse:
required:
- cost_sharing
type: object
properties:
cost_sharing:
allOf:
- $ref: '#/components/schemas/HealthInsuranceCostSharingConfigurationResponse'
description: Defines how the policy total cost is shared between employer and employee.
additionalProperties: false
EnrolmentIntentAssociatedPersonResponse:
required:
- dependent
- optional
- type
type: object
properties:
optional:
type: boolean
description: Indicates whether providing information for the related type is optional.
example: true
type:
allOf:
- $ref: '#/components/schemas/AssociatedPersonType'
description: The type of associated person.
dependent:
type: 'null'
allOf:
- $ref: '#/components/schemas/EnrolmentIntentDependentResponse'
description: Dependents-specific information if type is 'dependents'.
additionalProperties: false
EnrolmentIntentDependentResponse:
required:
- intent_id
- status
type: object
properties:
intent_id:
pattern: dmi_.+
type: string
description: Unique identifier for the dependents management intent. Prefixed with `dmi_`.
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
status:
allOf:
- $ref: '#/components/schemas/DependentStatus'
description: Current status of the dependent.
additionalProperties: false
TierBasedPricingResponse:
required:
- currency
- tiers
type: object
properties:
currency:
allOf:
- $ref: '#/components/schemas/CurrencyCode'
description: Currency code (e.g., 'eur', 'usd').
tiers:
type: array
items:
$ref: '#/components/schemas/PricingTierResponse'
description: Pricing tiers for different family compositions.
additionalProperties: false
SelectedOptionRequest:
required:
- option_id
type: object
properties:
option_id:
pattern: pco_.+
type: string
description: Option ID (prefixed with `pco_`).
example: pco_3b1333d87d9d4fd6ad83ba7f6b0e951a
sub_options:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/SelectedOptionRequest'
description: Sub-option selections, if applicable.
additionalProperties: false
PolicyPlanResponse:
required:
- currency
- description
- documents
- id
- name
type: object
properties:
id:
pattern: pl_.+
type: string
description: Unique identifier for the plan. Prefixed with pl_.
example: pl_3b1333d87d9d4fd6ad83ba7f6b0e951a
name:
type: string
description: Plan display name.
description:
type: string
description: Short description of the plan.
currency:
allOf:
- $ref: '#/components/schemas/CurrencyCode'
description: ISO 4217 currency code for pricing under this plan.
documents:
type: array
items:
$ref: '#/components/schemas/PlanDocumentResponse'
description: List of plan documents (e.g., IPIDs, T&Cs).
additionalProperties: false
PlanPricingResponse:
required:
- type
type: object
properties:
type:
allOf:
- $ref: '#/components/schemas/PlanPricingType'
description: Type of pricing structure
per_member:
type: 'null'
allOf:
- $ref: '#/components/schemas/PerMemberPricingResponse'
description: Per-member pricing details (populated when type is 'per_member').
tier_based:
type: 'null'
allOf:
- $ref: '#/components/schemas/TierBasedPricingResponse'
description: Tier-based pricing details (populated when type is 'tier_based').
additionalProperties: false
PlanCoverageOptionResponse:
required:
- id
- name
type: object
properties:
id:
pattern: pco_.+
type: string
description: Unique identifier for this coverage option. Prefixed with `pco_`.
example: pco_3b1333d87d9d4fd6ad83ba7f6b0e951a
name:
type: string
description: Display name for this coverage option.
description:
type:
- 'null'
- string
description: Longer explanation of this coverage option.
learn_more_url:
type:
- 'null'
- string
description: Link to learn more about this coverage option.
from_price:
type:
- 'null'
- number
description: Lowest applicable monthly price for this coverage option.
format: double
benefits:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/PlanCoverageOptionBenefitResponse'
description: Benefit items included with this coverage option.
sub_options:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/PlanCoverageOptionResponse'
description: Nested sub-options available when this option is selected.
eligibility_criteria:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/EmployerEligibilityCriterionResponse'
description: Eligibility criteria that must be met to select this coverage option.
additionalProperties: false
HealthInsuranceMemberSelectionCostSharingConfigurationResponse:
required:
- children
- partner
type: object
properties:
partner:
type: boolean
description: If a spouse/partner is covered.
example: true
children:
type: boolean
description: If children are covered.
example: true
additionalProperties: false
PlanPricingType:
enum:
- per_member
- tier_based
type: string
DependentStatus:
enum:
- processing
- confirmed
type: string
DependentsManagementIntentDependentStatus:
enum:
- pending_confirmation
- action_required
- ineligible
- processing
- restricted
- ready
type: string
MemberTypeCode:
enum:
- adult
- young_adult
- child
type: string
EnrolmentIntentResponse:
required:
- disclosures
- employee_id
- force_confirmation
- group_id
- id
- policy_enrolments
- status
type: object
properties:
id:
pattern: ei_.+
type: string
description: Unique identifier for the enrolment intent. Prefixed with `ei_`.
example: ei_3b1333d87d9d4fd6ad83ba7f6b0e951a
employee_id:
pattern: ee_.+
type: string
description: Identifier for the employee associated with this enrolment intent. Prefixed with `ee_`.
example: ee_3b1333d87d9d4fd6ad83ba7f6b0e951a
group_id:
pattern: gr_.+
type: string
description: Identifier for the group associated with this enrolment intent. Prefixed with `gr_`.
example: gr_3b1333d87d9d4fd6ad83ba7f6b0e951a
status:
allOf:
- $ref: '#/components/schemas/EnrolmentIntentStatus'
description: Current status of the enrolment intent.
force_confirmation:
type: boolean
description: 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: true
policy_enrolments:
type: array
items:
$ref: '#/components/schemas/EnrolmentIntentPolicyEnrolmentResponse'
description: Policy enrolment information
object:
type: string
description: Object type identifier.
readOnly: true
ineligibility_reason:
type: 'null'
allOf:
- $ref: '#/components/schemas/EnrolmentIntentInelgibilityReason'
description: If the enrolment intent status is `ineligible`, this field provides details about the reason for employees ineligibility.
policy_configuration:
type: 'null'
allOf:
- $ref: '#/components/schemas/PolicyConfigurationResponse'
description: Policy configuration associated with this enrolment intent.
action_required:
type: 'null'
allOf:
- $ref: '#/components/schemas/EnrolmentIntentActionRequiredResponse'
description: If the enrolment intent status is `action_required`, this field provides details about the action that needs to be taken to proceed with the enrolment.
pending_confirmation:
type: 'null'
allOf:
- $ref: '#/components/schemas/EnrolmentIntentPendingConfirmationResponse'
description: If the enrolment intent status is `pending_confirmation`, this field provides details about the pending confirmation state.
disclosures:
type: array
items:
$ref: '#/components/schemas/DisclosureResponse'
description: Disclosures associated with this intent.
additionalProperties: false
RequirementObjectType:
enum:
- employee
- employer
- associated_person
type: string
HealthInsuranceCostSharingType:
enum:
- member_count
- member_selection
- percentage
- policyholder_only
- family_type
type: string
x-fern-enum:
member_count:
description: The number of additional adults and children to cover is specified.
member_selection:
description: Dependent categories to cover are selected (partner and/or children).
percentage:
description: A percentage of the total premium is covered.
policyholder_only:
description: Only the policyholder is covered.
family_type:
description: Coverage is based on a predefined family tier (e.g. Single, Couple, Family).
EnrolmentIntentConfirmationType:
enum:
- confirm_enrolment
type: string
DisclosureType:
enum:
- intermediary_role
- intermediary_commission
- underwriter_disclaimer
- anti_selection_notice
- statement_of_needs
- product_information
- pre_existing_conditions
- statutory_warning
type: string
EmployerEligibilityCriterionType:
enum:
- employees_count
- members_count
- industry_exclusions
type: string
MembersCountDetails:
type: object
properties:
min:
type:
- 'null'
- integer
description: Minimum number of members required.
format: int32
max:
type:
- 'null'
- integer
description: Maximum number of members allowed.
format: int32
additionalProperties: false
CurrencyCode:
enum:
- 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
type: string
PricingTierResponse:
required:
- annual_premium
- code
- display_dependent_requirements
- display_name
- monthly_premium
type: object
properties:
code:
allOf:
- $ref: '#/components/schemas/FamilyTierCode'
description: Tier code.
display_name:
type: string
description: Display name for the tier.
monthly_premium:
type: number
description: Monthly premium amount for this tier.
format: double
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kota/refs/heads/main/openapi/kota-enrolment-intents-api-openapi.yml