> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/api/employee-flow/dependent-management/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server. # Dependent Management > Add, remove, and confirm dependents during enrolment or after policy issuance using Kota's Dependents Management Intent API 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. > **Info** > > Before starting, ensure you've completed: > > * [Authentication](/core-components/authentication): API key setup and idempotency > * [Employer and employee management](/core-components/employer-employee-management): syncing employers, employees, and associated persons > * [Webhooks and events](/core-components/webhooks-and-events): receiving asynchronous updates > > This guide assumes the employee either has an in-flight [enrolment intent](/api/employee-flow/employee-enrolment) > that requires dependent information, or an issued policy that can be amended. --- ## 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: | Parent intent | When it is used | How the DMI starts | | ------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | `enrolment_intent` | The provider needs dependent information before the employee can be enrolled. | Kota exposes a `dmi_` ID in the enrolment intent's `action_required.associated_persons.dependent.intent_id`. | | `policy_amendment_intent` | The employee wants to add or remove dependents after a policy has been issued. | You create a policy amendment intent, then create the DMI sub-intent while the amendment is `action_required`. | 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. > **Note** > > Dependents management intents currently apply to dependents. Beneficiary information may > also appear as an associated-person requirement during enrolment, but it is handled by > the action payload for that enrolment intent rather than by the DMI endpoints documented > here. ### Lifecycle ```mermaid flowchart TD parent[Parent intent requires dependents] action_required[action_required] manage[Add or remove dependents] confirm[Confirm dependent list] processing[processing] completed[completed] not_undertaken[not_undertaken] parent --> action_required action_required --> manage manage --> confirm confirm --> processing processing --> completed action_required --> not_undertaken ``` ### Statuses | Status | Meaning | What you do | | ----------------- | --------------------------------------------------- | ----------------------------------------------------------------------- | | `action_required` | The dependent list still needs input. | Add or remove dependents, then confirm or cancel. | | `processing` | Kota is validating and applying the dependent list. | Wait. Transient. | | `completed` | The dependent list has been accepted by the DMI. | Return to the parent intent and continue that flow. | | `not_undertaken` | The DMI was cancelled or will not proceed. | Terminal. Create a new DMI from the parent flow if retrying is allowed. | Each dependent in the DMI also has its own status: | Dependent status | Meaning | | ---------------------- | ------------------------------------------------------------------------------ | | `ready` | The associated person can be included. | | `pending_confirmation` | The dependent needs confirmation before the list can proceed. | | `processing` | Kota is evaluating this dependent. | | `ineligible` | This associated person cannot be added as a dependent for this policy or plan. | | `restricted` | This associated person cannot currently be confirmed for this DMI. | > **Warning** > > You cannot confirm a DMI while any selected dependent is `ineligible` or `restricted`. > Remove those dependents first, then confirm the list. --- ## 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`** ```bash cURL 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`** ```bash cURL 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: ```json { "status": "action_required", "action_required": { "code": "provide_dependant_information", "reason": "Dependant information is required", "reason_description": "Provide details for the employee's dependants to continue.", "due_by": "2026-07-06T00:00:00Z", "associated_persons": { "type": "dependents", "optional": false, "dependent": { "intent_id": "dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234", "status": "processing" } } } } ``` 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`** ```bash cURL 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: ```json { "items": [ { "associated_person_id": "ap_11111111111111111111111111111111", "first_name": "Alex", "last_name": "Rivers", "date_of_birth": "2021-04-15", "sex_at_birth": "female", "relationship": "child", "eligibility_status": "eligible", "ineligibility_reason": null }, { "associated_person_id": "ap_22222222222222222222222222222222", "first_name": "Jamie", "last_name": "Rivers", "date_of_birth": "1980-02-10", "sex_at_birth": "male", "relationship": "partner", "eligibility_status": "ineligible", "ineligibility_reason": "This plan does not support partner dependents." } ], "page": 1, "page_size": 100, "total_count": 2 } ``` 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`** ```bash cURL 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: ```json { "id": "dmi_8f3a1c20d4e9457bb1f0a9c2e7d61234", "object": "dependents_management_intent", "parent_intent_id": "ei_8f3a1c20d4e9457bb1f0a9c2e7d61234", "parent_intent_type": "enrolment_intent", "status": "action_required", "dependents": [ { "associated_person_id": "ap_11111111111111111111111111111111", "status": "ready" } ], "plan": { "id": "pl_3b1333d87d9d4fd6ad83ba7f6b0e951a", "name": "Health Plan Level 2", "description": "International health cover with family dependents.", "pricing": { "type": "per_member", "per_member": { "currency": "eur", "member_type_pricing": [ { "code": "adult", "display_name": "Adult", "monthly_premium": 150.00 }, { "code": "child", "display_name": "Child", "monthly_premium": 75.00 } ] }, "tier_based": null } } } ``` --- ## 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`** ```bash cURL 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`** ```bash cURL 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`. > **Info** > > Completing the DMI does not always mean the parent flow is finished. For enrolment, keep > following the enrolment intent until it becomes `pending_confirmation`, `enrolling`, or > `enrolled`. For policy amendments, keep following the policy amendment intent until it is > `amended` or terminal. --- ## 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`** ```bash cURL 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: | Status | Meaning | What you do | | ---------------------- | ------------------------------------------------------------- | ------------------------------------------------- | | `action_required` | Dependent information must be supplied. | Create and complete the DMI. | | `awaiting_quote` | Kota is waiting for the provider to quote the amended policy. | Wait. | | `pending_confirmation` | The employee must accept the amendment quote. | Show the quote and confirm or cancel. | | `processing` | Kota is applying the amendment with the provider. | Wait. | | `amended` | The policy was updated. | Done. | | `processing_error` | The provider rejected or failed the amendment. | Show the reason and stop this attempt. | | `not_undertaken` | The amendment was cancelled or expired. | Terminal. Create a new amendment intent to retry. | 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`** ```bash cURL 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`** ```bash cURL 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`** ```bash cURL 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`** ```bash cURL 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`** ```bash cURL 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: | Event | Fired when | Suggested UI | | ---------------------------------------------- | -------------------------------------------- | ----------------------------- | | `dependents_management_intent.action_required` | Dependent information is needed | Dependent selection form | | `dependents_management_intent.completed` | The dependent list was accepted | Return to parent flow | | `dependents_management_intent.not_undertaken` | The DMI was cancelled or stopped | Show cancelled state | | `enrolment_intent.action_required` | Enrolment requires dependent information | Start or resume DMI handling | | `enrolment_intent.pending_confirmation` | Employee must confirm enrolment | Disclosures + confirm/reject | | `enrolment_intent.enrolling` | Enrolment is in progress with the provider | Holding screen | | `enrolment_intent.enrolled` | Employee was enrolled and policy issued | Success / policy details | | `policy_amendment_intent.action_required` | Amendment requires dependent information | Create or resume DMI handling | | `policy_amendment_intent.awaiting_quote` | Kota is waiting for a provider quote | Wait / loading | | `policy_amendment_intent.pending_confirmation` | Amendment quote needs employee confirmation | Quote review and confirm | | `policy_amendment_intent.processing` | Amendment is being applied with the provider | Wait / loading | | `policy_amendment_intent.amended` | Policy was updated | Success / policy details | | `policy_amendment_intent.processing_error` | Amendment failed | Show `reason` | | `policy_amendment_intent.not_undertaken` | Amendment was cancelled or expired | Allow restarting | 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](/api/employee-flow/employee-enrolment): enrol employees and handle enrolment intent statuses * [Assign Employee to a Group](/api/employee-flow/assign-employee-to-group): add employees to benefit groups before enrolment * [Webhooks and events](/core-components/webhooks-and-events): event handling * [API Errors](/api-reference/errors): error response format > Add, remove, and confirm dependents during enrolment or after policy issuance using Kota's Dependents Management Intent API