Dependent Management

This guide walks you through managing an employee’s dependents using Dependents Management Intents. You’ll learn how the intent fits into enrolment and policy amendment flows, how to add or remove existing associated persons, and how to confirm the final dependent list.

Overview

A dependents management intent represents the dependent list that should be applied as part of a larger parent workflow. It is always attached to a parent intent:

The DMI itself does not create associated persons. Create or update associated persons on the employee first, then add eligible ap_ IDs to the DMI.

Lifecycle

Statuses

Each dependent in the DMI also has its own status:

Step 1: Prepare associated persons

Dependents must exist as associated persons before they can be added to a DMI. If the person does not already exist for the employee, create them first.

Endpoint: POST /employees/{employee_id}/associated_persons

$
curl -X POST "https://api.kota.io/employees/ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e/associated_persons" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "Idempotency-Key: 7b7f1b2c-3d4e-5f60-8a1b-2c3d4e5f6071" \
>
  -d '{
>
    "first_name": "Alex",
>
    "last_name": "Rivers",
>
    "date_of_birth": "2021-04-15",
>
    "sex_at_birth": "female",
>
    "relationship_type": "child",
>
    "email": null,
>
    "phone_number": null
>
  }'

The response contains the associated person ID, prefixed ap_. Use that ID when adding the person to a DMI.

To reuse an existing person, list associated persons for the employee:

Endpoint: GET /employees/{employee_id}/associated_persons

$
curl -X GET "https://api.kota.io/employees/ee_2b9c4d6e8f0a1b3c5d7e9f0a1b2c3d4e/associated_persons" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Step 2: Handle dependents during enrolment

During enrolment, Kota may move the parent enrolment intent to action_required with code: "provide_dependant_information". The action payload includes the DMI ID:

1
{
2
  "status": "action_required",
3
  "action_required": {
4
    "code": "provide_dependant_information",
5
    "reason": "Dependant information is required",
6
    "reason_description": "Provide details for the employee's dependants to continue.",
7
    "due_by": "2026-07-06T00:00:00Z",
8
    "associated_persons": {
9
      "type": "dependents",
10
      "optional": false,
11
      "dependent": {
12
        "intent_id": "dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234",
13
        "status": "processing"
14
      }
15
    }
16
  }
17
}

Store the dmi_ ID and use it for the DMI endpoints below. The parent enrolment intent remains the source of truth for the overall enrolment flow, so keep watching enrolment intent webhooks after the DMI is completed.

Step 3: Check dependent eligibility

Retrieve eligibility before adding dependents to the DMI. This returns the employee’s associated persons with their eligibility for the policy or plan attached to the parent intent.

Endpoint: GET /dependents_management_intents/{dependents_management_intent_id}/associated_persons_eligibility

$
curl -X GET "https://api.kota.io/dependents_management_intents/dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234/associated_persons_eligibility?page=1&page_size=100" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Example response:

1
{
2
  "items": [
3
    {
4
      "associated_person_id": "ap_11111111111111111111111111111111",
5
      "first_name": "Alex",
6
      "last_name": "Rivers",
7
      "date_of_birth": "2021-04-15",
8
      "sex_at_birth": "female",
9
      "relationship": "child",
10
      "eligibility_status": "eligible",
11
      "ineligibility_reason": null
12
    },
13
    {
14
      "associated_person_id": "ap_22222222222222222222222222222222",
15
      "first_name": "Jamie",
16
      "last_name": "Rivers",
17
      "date_of_birth": "1980-02-10",
18
      "sex_at_birth": "male",
19
      "relationship": "partner",
20
      "eligibility_status": "ineligible",
21
      "ineligibility_reason": "This plan does not support partner dependents."
22
    }
23
  ],
24
  "page": 1,
25
  "page_size": 100,
26
  "total_count": 2
27
}

Show ineligibility_reason to the employee when present and do not add ineligible associated persons to the DMI.

Step 4: Add dependents

Add one or more eligible associated persons to the DMI.

Endpoint: POST /dependents_management_intents/{dependents_management_intent_id}/dependents

$
curl -X POST "https://api.kota.io/dependents_management_intents/dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234/dependents" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "associated_person_ids": [
>
      "ap_11111111111111111111111111111111"
>
    ]
>
  }'

The response is the updated DMI:

1
{
2
  "id": "dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234",
3
  "object": "dependents_management_intent",
4
  "parent_intent_id": "ei_8f3a1c20d4e9457bb1f0a9c2e7d61234",
5
  "parent_intent_type": "enrolment_intent",
6
  "status": "action_required",
7
  "dependents": [
8
    {
9
      "associated_person_id": "ap_11111111111111111111111111111111",
10
      "status": "ready"
11
    }
12
  ],
13
  "plan": {
14
    "id": "pl_3b1333d87d9d4fd6ad83ba7f6b0e951a",
15
    "name": "Health Plan Level 2",
16
    "description": "International health cover with family dependents.",
17
    "pricing": {
18
      "type": "per_member",
19
      "per_member": {
20
        "currency": "eur",
21
        "member_type_pricing": [
22
          { "code": "adult", "display_name": "Adult", "monthly_premium": 150.00 },
23
          { "code": "child", "display_name": "Child", "monthly_premium": 75.00 }
24
        ]
25
      },
26
      "tier_based": null
27
    }
28
  }
29
}

Step 5: Remove dependents if needed

If the employee changes their selection, or if a selected dependent is ineligible or restricted, remove that associated person from the DMI.

Endpoint: DELETE /dependents_management_intents/{dependents_management_intent_id}/dependents/{associated_person_id}

$
curl -X DELETE "https://api.kota.io/dependents_management_intents/dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234/dependents/ap_11111111111111111111111111111111" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Step 6: Confirm the dependent list

When the selected dependent list is final and no selected dependent is ineligible or restricted, confirm the DMI.

Endpoint: POST /dependents_management_intents/{dependents_management_intent_id}/confirm

$
curl -X POST "https://api.kota.io/dependents_management_intents/dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234/confirm" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Confirming returns 204 No Content and moves the DMI to processing.

Step 7: Start a dependent change after policy issuance

To add or remove dependents after a policy has been issued, create a policy amendment intent for the policy. Request the dependents change type.

Endpoint: POST /policies/{policy_id}/policy_amendment_intents

$
curl -X POST "https://api.kota.io/policies/p_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90/policy_amendment_intents" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "Idempotency-Key: 2e0f1b2c-3d4e-5f60-8a1b-2c3d4e5f6071" \
>
  -d '{
>
    "amendment_reason": {
>
      "type": "qualifying_life_event",
>
      "qualifying_life_event": {
>
        "event": "birth_of_child",
>
        "event_date": "2026-06-15",
>
        "reason": "Employee is adding a newborn child to their policy."
>
      }
>
    },
>
    "requested_changes": [
>
      {
>
        "change_type": "dependents"
>
      }
>
    ]
>
  }'

The amendment intent moves through its own lifecycle:

When the amendment is action_required with code: "provide_dependents_information", create the DMI sub-intent:

Endpoint: POST /policies/{policy_id}/policy_amendment_intents/{id}/create_dependents_management_intent

$
curl -X POST "https://api.kota.io/policies/p_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90/policy_amendment_intents/pai_8f3a1c20d4e9457bb1f0a9c2e7d61234/create_dependents_management_intent" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Use the returned dmi_ ID with Steps 3 through 6 to check eligibility, add or remove dependents, and confirm the dependent list.

After the DMI is completed, retrieve the parent amendment intent and continue from its current status:

Endpoint: GET /policies/{policy_id}/policy_amendment_intents/{policy_amendment_intent_id}

$
curl -X GET "https://api.kota.io/policies/p_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90/policy_amendment_intents/pai_8f3a1c20d4e9457bb1f0a9c2e7d61234" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

If the amendment reaches pending_confirmation, show the employee the quote and confirmation reason, then confirm:

Endpoint: POST /policies/{policy_id}/policy_amendment_intents/{policy_amendment_intent_id}/confirm

$
curl -X POST "https://api.kota.io/policies/p_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90/policy_amendment_intents/pai_8f3a1c20d4e9457bb1f0a9c2e7d61234/confirm" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel if the employee does not proceed

If the employee decides not to continue while the DMI is still action_required, cancel the DMI.

Endpoint: POST /dependents_management_intents/{dependents_management_intent_id}/cancel

$
curl -X POST "https://api.kota.io/dependents_management_intents/dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234/cancel" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

For post-policy amendments, you may also need to cancel the parent amendment intent if the employee has abandoned the whole amendment.

Endpoint: POST /policies/{policy_id}/policy_amendment_intents/{id}/cancel

$
curl -X POST "https://api.kota.io/policies/p_4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f90/policy_amendment_intents/pai_8f3a1c20d4e9457bb1f0a9c2e7d61234/cancel" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks summary

Handle DMI events and the parent-intent events for the flow you are in:

Each webhook identifies the resource that changed. Re-fetch the current DMI or parent intent before updating your UI, because status may have moved again by the time your handler runs.

Best practices

• Create associated persons first. DMI endpoints add existing ap_ IDs, not raw dependent details.
• Use eligibility before selection. Check associated_persons_eligibility and block ineligible dependents before calling confirm.
• Drive off parent and child statuses. The DMI tracks dependent collection; the parent intent tracks enrolment or policy amendment completion.
• Respect deadlines. Surface due_by from the parent action_required or pending_confirmation payload so employees act in time.
• Handle unknown enum values. New statuses or reason codes may be added as providers expand. Prefer displaying human-readable reasons when available.
• Cancel intentionally. Cancel the DMI when dependent collection is abandoned, and cancel the parent policy amendment if the whole policy change should stop.

Next steps

• Employee Enrolment: enrol employees and handle enrolment intent statuses
• Assign Employee to a Group: add employees to benefit groups before enrolment
• Webhooks and events: event handling
• API Errors: error response format