For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Get access
Getting Started Key Concepts Integration Types Core Components Embed Hosted API API Reference
  • API Reference
    • Contribution Reports
    • Events and Webhooks
      • GETList all enrolment intents
      • POSTCreate a new enrolment intent
      • GETRetrieve an enrolment intent
      • PUTUpdate policy configuration enrolment intent
      • POSTConfirm an enrolment intent
    • API Errors
Get access
LogoLogo
API ReferenceEnrolment Intents

Create a new enrolment intent

POST
/enrolment_intents
POST
/enrolment_intents
$curl -X POST https://test.api.kota.io/enrolment_intents \
>     -H "Authorization: Bearer <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "employee_id": "ee_7f9c2d3a4b5e6f7a8c9d0e1f2a3b4c5d",
>  "group_id": "gr_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
>  "force_confirmation": true
>}'
1{
2  "id": "ei_9f8e7d6c5b4a3f2e1d0c9b8a7e6d5c4b",
3  "employee_id": "ee_7f9c2d3a4b5e6f7a8c9d0e1f2a3b4c5d",
4  "group_id": "gr_1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p",
5  "status": "processing",
6  "force_confirmation": true,
7  "policy_enrolments": [
8    {
9      "type": "health_insurance",
10      "estimated_effective_from": "2024-12-01",
11      "provider": {
12        "id": "pr_4e5f6a7b8c9d0e1f2a3b4c5d6e7f8g9h",
13        "name": "Acme Health Insurance",
14        "description": "Leading provider of comprehensive health insurance plans.",
15        "logo_url": "https://acmehealth.com/assets/logo.png"
16      },
17      "plan": {
18        "id": "pl_0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p",
19        "name": "Premium Health Plan",
20        "description": "Full coverage health insurance plan with dental and vision benefits.",
21        "currency": "eur",
22        "documents": [
23          {
24            "title": "Insurance Product Information Document",
25            "link": "https://acmehealth.com/docs/ipid-premium.pdf",
26            "type": "ipid"
27          }
28        ]
29      },
30      "id": "p_5d6e7f8g9h0a1b2c3d4e5f6g7h8i9j0k"
31    }
32  ],
33  "disclosures": [
34    {
35      "category": "regulatory",
36      "type": "intermediary_role",
37      "text": "This policy is offered through an intermediary who may receive commission."
38    }
39  ],
40  "object": "enrolment_intent"
41}

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.

Previous

List all enrolment intents

Next

Retrieve an enrolment intent

Built with

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Request

This endpoint expects an object.
employee_idstringRequiredformat: "ee_.+"

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

group_idstringRequiredformat: "gr_.+"

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

force_confirmationbooleanRequired

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_configurationobjectOptional
Policy configuration associated with this enrolment intent. You do not have to explicitly provide this field if you want to use the default policy configuration for the group. This simply lets you override specific settings for this enrolment intent.

Response

OK
idstringformat: "ei_.+"

Unique identifier for the enrolment intent. Prefixed with ei_.

employee_idstringformat: "ee_.+"

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

group_idstringformat: "gr_.+"

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

statusenum
Current status of the enrolment intent.
force_confirmationboolean

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_enrolmentslist of objects
Policy enrolment information
disclosureslist of objects
Disclosures associated with this intent.
objectstringRead-only
Object type identifier.
ineligibility_reasonobject

If the enrolment intent status is ineligible, this field provides details about the reason for employees ineligibility.

policy_configurationobject
Policy configuration associated with this enrolment intent.
action_requiredobject

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_confirmationobject

If the enrolment intent status is pending_confirmation, this field provides details about the pending confirmation state.

Errors

400
Bad Request Error
404
Not Found Error