Kota enrolmentIntents API
The enrolmentIntents API from Kota — 7 operation(s) for enrolmentintents.
The enrolmentIntents API from Kota — 7 operation(s) for enrolmentintents.
openapi: 3.1.0
info:
title: API Reference Associated Persons enrolmentIntents API
version: 1.0.0
servers:
- url: https://test.api.kota.io
description: test
- url: https://api.kota.io
description: production
tags:
- name: enrolmentIntents
paths:
/enrolment_intents:
get:
operationId: list-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.
tags:
- enrolmentIntents
parameters:
- name: employee_id
in: query
description: Filters enrolment intents by employee.
required: false
schema:
type: string
- name: group_id
in: query
description: Filters enrolment intents by group.
required: false
schema:
type: string
- 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`.'
required: false
schema:
type: string
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
required: false
schema:
type: integer
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
required: false
schema:
type: integer
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponsePagedList'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
post:
operationId: create-enrolment-intent
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.
tags:
- enrolmentIntents
parameters:
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
- 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)
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnrolmentIntentRequest'
/enrolment_intents/{enrolment_intent_id}:
get:
operationId: retrieve-enrolment-intent
summary: Retrieve an enrolment intent
description: Retrieves an `enrolment_intent` object.
tags:
- enrolmentIntents
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
operationId: update-enrolment-intent-configuration
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`.
tags:
- enrolmentIntents
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyConfigurationRequest'
/enrolment_intents/{enrolment_intent_id}/requirements:
get:
operationId: list-enrolment-intent-requirements
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.
tags:
- enrolmentIntents
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
type: string
- name: object_type
in: query
description: Filter by object type (employee or employer)
required: false
schema:
$ref: '#/components/schemas/RequirementObjectTypeEnumParameter'
- name: object_id
in: query
description: Filter by object ID (employee ID or employer ID)
required: false
schema:
type: string
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
required: false
schema:
type: integer
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
required: false
schema:
type: integer
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EnrolmentIntentRequirementResponsePagedList'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/confirm:
post:
operationId: confirm-enrolment-intent
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.
tags:
- enrolmentIntents
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'204':
description: No Content
content:
application/json:
schema:
$ref: '#/components/schemas/Enrolment Intents_ConfirmEnrolmentIntent_Response_204'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/reject:
post:
operationId: reject-enrolment-intent
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.
tags:
- enrolmentIntents
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'204':
description: No Content
content:
application/json:
schema:
$ref: '#/components/schemas/Enrolment Intents_RejectEnrolmentIntent_Response_204'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/enrolment_intents/{enrolment_intent_id}/coverage-selections:
post:
operationId: submit-enrolment-intent-coverage-selections
summary: Submit coverage selections for an enrolment intent
description: Submits plan coverage option selections for an enrolment intent in the `addon_selection_required` status.
tags:
- enrolmentIntents
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'204':
description: No Content
content:
application/json:
schema:
$ref: '#/components/schemas/Enrolment Intents_SubmitEnrolmentIntentCoverageSelections_Response_204'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitCoverageSelectionsRequest'
/enrolment_intents/{enrolment_intent_id}/create_dependents_management_intent:
post:
operationId: create-dependents-management-intent-for-enrolment-intent
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.
tags:
- enrolmentIntents
parameters:
- name: enrolment_intent_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Authorization header using the Bearer scheme
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DependentsManagementIntentResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
PlanWithPricingResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the plan. Prefixed with `pl_`.
name:
type: string
description: The name of the plan.
description:
type: string
description: Description of the plan.
pricing:
$ref: '#/components/schemas/PlanPricingResponse'
description: Pricing information for the plan.
required:
- id
- name
- description
- pricing
title: PlanWithPricingResponse
PlanCoverageOptionInputType:
type: string
enum:
- single_select
- multi_select
title: PlanCoverageOptionInputType
PolicyType:
type: string
enum:
- health_insurance
- life_assurance
title: PolicyType
PlanCoverageOptionScope:
type: string
enum:
- group_policy
- policy
- member
title: PlanCoverageOptionScope
RequirementType:
type: string
enum:
- group_quote_intent
- group_policy_intent
- dependent_management_intent
- policy_amendment_intent
- enrolment_intent
title: RequirementType
PlanCoverageResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the coverage selection. Prefixed with `pc_`.
name:
type: string
description: Title for this coverage selection. Typically used as the display heading.
description:
type:
- string
- 'null'
description: Full description of this coverage selection.
scope:
$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:
$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.
min_selections:
type:
- integer
- 'null'
description: Minimum required selections (multi-select only).
max_selections:
type:
- integer
- 'null'
description: Maximum allowed selections (multi-select only).
sort_order:
type:
- integer
- 'null'
description: Display ordering hint.
group_label:
type:
- string
- 'null'
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.
required:
- id
- name
- scope
- input_type
- required
- options
title: PlanCoverageResponse
HealthInsuranceFamilyTypeCostSharingConfigurationResponse:
type: object
properties:
type:
$ref: '#/components/schemas/HealthInsuranceFamilyCostSharingType'
description: Employer coverage family type
required:
- type
title: HealthInsuranceFamilyTypeCostSharingConfigurationResponse
PlanCoverageOptionSelectionRequest:
type: object
properties:
configuration_id:
type: string
description: Configuration ID (prefixed with `pc_`).
options:
type: array
items:
$ref: '#/components/schemas/SelectedOptionRequest'
description: Selected options with optional sub-options.
required:
- configuration_id
- options
title: PlanCoverageOptionSelectionRequest
DependentsManagementIntentStatus:
type: string
enum:
- action_required
- processing
- completed
- not_undertaken
title: DependentsManagementIntentStatus
PolicyConfigurationResponse:
type: object
properties:
desired_policy_start_date:
type:
- string
- 'null'
format: date
description: Desired policy start date, not guaranteed to be honoured by the provider.
enrolment_date:
type:
- string
- 'null'
format: date
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.
title: PolicyConfigurationResponse
HealthInsurancePolicyConfigurationResponse:
type: object
properties:
cost_sharing:
$ref: '#/components/schemas/HealthInsuranceCostSharingConfigurationResponse'
description: Defines how the policy total cost is shared between employer and employee.
required:
- cost_sharing
title: HealthInsurancePolicyConfigurationResponse
EnrolmentIntentAssociatedPersonResponse:
type: object
properties:
optional:
type: boolean
description: Indicates whether providing information for the related type is optional.
type:
$ref: '#/components/schemas/AssociatedPersonType'
description: The type of associated person.
dependent:
$ref: '#/components/schemas/EnrolmentIntentDependentResponse'
description: Dependents-specific information if type is 'dependents'.
required:
- optional
- type
- dependent
title: EnrolmentIntentAssociatedPersonResponse
EnrolmentIntentDependentResponse:
type: object
properties:
intent_id:
type: string
description: Unique identifier for the dependents management intent. Prefixed with `dmi_`.
status:
$ref: '#/components/schemas/DependentStatus'
description: Current status of the dependent.
required:
- intent_id
- status
title: EnrolmentIntentDependentResponse
TierBasedPricingResponse:
type: object
properties:
currency:
$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.
required:
- currency
- tiers
title: TierBasedPricingResponse
SelectedOptionRequest:
type: object
properties:
option_id:
type: string
description: Option ID (prefixed with `pco_`).
sub_options:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/SelectedOptionRequest'
description: Sub-option selections, if applicable.
required:
- option_id
title: SelectedOptionRequest
PolicyPlanResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the plan. Prefixed with pl_.
name:
type: string
description: Plan display name.
description:
type: string
description: Short description of the plan.
currency:
$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).
required:
- id
- name
- description
- currency
- documents
title: PolicyPlanResponse
PlanPricingResponse:
type: object
properties:
type:
$ref: '#/components/schemas/PlanPricingType'
description: Type of pricing structure
per_member:
$ref: '#/components/schemas/PerMemberPricingResponse'
description: Per-member pricing details (populated when type is 'per_member').
tier_based:
$ref: '#/components/schemas/TierBasedPricingResponse'
description: Tier-based pricing details (populated when type is 'tier_based').
required:
- type
title: PlanPricingResponse
PlanCoverageOptionResponse:
type: object
properties:
id:
type: string
description: Unique identifier for this coverage option. Prefixed with `pco_`.
name:
type: string
description: Display name for this coverage option.
description:
type:
- string
- 'null'
description: Longer explanation of this coverage option.
learn_more_url:
type:
- string
- 'null'
description: Link to learn more about this coverage option.
from_price:
type:
- number
- 'null'
format: double
description: Lowest applicable monthly price for this coverage option.
benefits:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/PlanCoverageOptionBenefitResponse'
description: Benefit items included with this coverage option.
sub_options:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/PlanCoverageOptionResponse'
description: Nested sub-options available when this option is selected.
eligibility_criteria:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/EmployerEligibilityCriterionResponse'
description: Eligibility criteria that must be met to select this coverage option.
required:
- id
- name
title: PlanCoverageOptionResponse
HealthInsuranceMemberSelectionCostSharingConfigurationResponse:
type: object
properties:
partner:
type: boolean
description: If a spouse/partner is covered.
children:
type: boolean
description: If children are covered.
required:
- partner
- children
title: HealthInsuranceMemberSelectionCostSharingConfigurationResponse
PlanPricingType:
type: string
enum:
- per_member
- tier_based
title: PlanPricingType
DependentStatus:
type: string
enum:
- processing
- confirmed
title: DependentStatus
DependentsManagementIntentDependentStatus:
type: string
enum:
- pending_confirmation
- action_required
- ineligible
- processing
- restricted
- ready
title: DependentsManagementIntentDependentStatus
MemberTypeCode:
type: string
enum:
- adult
- young_adult
- child
title: MemberTypeCode
EnrolmentIntentResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the enrolment intent. Prefixed with `ei_`.
employee_id:
type: string
description: Identifier for the employee associated with this enrolment intent. Prefixed with `ee_`.
group_id:
type: string
description: Identifier for the group associated with this enrolment intent. Prefixed with `gr_`.
status:
$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.
policy_enrolments:
type: array
items:
$ref: '#/components/schemas/EnrolmentIntentPolicyEnrolmentResponse'
description: Policy enrolment information
object:
type: string
description: Object type identifier.
ineligibility_reason:
$ref: '#/components/schemas/EnrolmentIntentInelgibilityReason'
description: If the enrolment intent status is `ineligible`, this field provides details about the reason for employees ineligibility.
policy_configuration:
$ref: '#/components/schemas/PolicyConfigurationResponse'
description: Policy configuration associated with this enrolment intent.
action_required:
$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:
$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.
required:
- id
- employee_id
- group_id
- status
- force_confirmation
- policy_enrolments
- disclosures
title: EnrolmentIntentResponse
RequirementObjectType:
type: string
enum:
- employee
- employer
- associated_person
title: RequirementObjectType
HealthInsuranceCostSharingType:
type: string
enum:
- member_count
- member_selection
- percentage
- policyholder_only
- family_type
title: HealthInsuranceCostSharingType
EnrolmentIntentConfirmationType:
type: string
enum:
- confirm_enrolment
title: EnrolmentIntentConfirmationType
DisclosureType:
type: string
enum:
- intermediary_role
- intermediary_commission
- underwriter_disclaimer
- anti_selection_notice
- statement_of_needs
- product_information
- pre_existing_conditions
- statutory_warning
title: DisclosureType
EmployerEligibilityCriterionType:
type: string
enum:
- employees_count
- members_count
- industry_exclusions
title: EmployerEligibilityCriterionType
MembersCountDetails:
type: object
properties:
min:
type:
- integer
- 'null'
description: Minimum number of members required.
max:
type:
- integer
- 'null'
description: Maximum number of members allowed.
title: MembersCountDetails
CurrencyCode:
type: string
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
title: CurrencyCode
PricingTierResponse:
type: object
properties:
code:
$ref: '#/components/schemas/FamilyTierCode'
description: Tier code.
display_name:
type: string
description: Display name for the tier.
monthly_premium:
type: number
format: double
description: Monthly premium amount for this tier.
annual_premium:
type: number
format: double
description: Annual premium amount for this tier.
display_dependent_requirements:
type: string
description: Description of dependent requirements for this tier.
required:
- code
- display_name
- monthly_premium
- annual_premium
- display_dependent_requirements
title: PricingTierResponse
HealthInsurancePercentageCostSharingConfigurationResponse:
type: object
properties:
percentage:
type: integer
description: "Employer coverage percentage:\n For 40% send 40.\n For 100% send 100."
required:
- percentage
title: HealthInsurancePercentageCostSharingConfigurationResponse
Enrolment Intents_RejectEnrolmentIntent_Response_204:
type: object
properties: {}
description: Empty response body
title: Enrolment Intents_RejectEnrolmentIntent_Response_204
MemberTypePricingResponse:
type: object
properties:
code:
$ref: '#/components/schemas/MemberTypeCode'
description: Member type code.
display_name:
type: string
description: Display name for the member type.
monthly_premium:
type: number
format: double
description: Monthly premium amount.
required:
- code
- display_name
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kota/refs/heads/main/openapi/kota-enrolmentintents-api-openapi.yml