> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kota.io/api-reference/enrolment-intents/create-dependents-management-intent-for-enrolment-intent/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server.

# Create a dependents management intent for an enrolment intent

POST https://test.api.kota.io/enrolment_intents/{enrolment_intent_id}/create_dependents_management_intent

Creates a dependents management intent as a sub-intent of an enrolment intent. The enrolment intent must be in `pending_confirmation` status.

Reference: https://docs.kota.io/api-reference/enrolment-intents/create-dependents-management-intent-for-enrolment-intent

## Authentication

- `Authorization` header (bearer token, required) — Authorization header using the Bearer scheme

## Servers

- `https://test.api.kota.io` (test, default)
- `https://api.kota.io` (production)

## Request

### Path parameters

- `enrolment_intent_id` (string, required)

### Headers

- `X-Platform-Id` (string, optional) — The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers.

## Response

### 200

OK

- `id` (string, required) — Unique identifier for the dependents management intent. Prefixed with `dmi_`.
- `parent_intent_id` (string, required) — The parent intent ID (e.g. Policy Amendment Intent ID). Prefixed based on type.
- `parent_intent_type` (enum, required) — The type of parent intent.
  - Allowed values: `policy_amendment_intent`, `enrolment_intent`
- `status` (enum, required) — Current status of the dependents management intent.
  - Allowed values: `action_required`, `processing`, `completed`, `not_undertaken`
- `dependents` (list of DependentInfoResponse, required) — List of dependents being managed.
- `plan` (PlanWithPricingResponse, required) — Plan information including pricing details.
- `disclosures` (list of DisclosureResponse, required) — Disclosures associated with this intent.
- `object` (string, optional) — Object type identifier.
- `coverage_options` (list of PlanCoverageResponse, optional, nullable) — Available member-scoped coverage options for the plan. Present when the plan has member-scoped coverage configurations.
- `action_required` (DependentsManagementIntentActionRequiredResponse, optional) — Details of the action required from the caller. Populated only when `status` is `action_required` and a required action has been recorded on the intent (e.g. restricted dependents detected by compliance screening).

## Errors

### 400 Bad Request Error

Bad Request

- `type` (string, optional, nullable)
- `title` (string, optional, nullable)
- `status` (integer, optional, nullable)
- `detail` (string, optional, nullable)
- `instance` (string, optional, nullable)

### 404 Not Found Error

Not Found

- `type` (string, optional, nullable)
- `title` (string, optional, nullable)
- `status` (integer, optional, nullable)
- `detail` (string, optional, nullable)
- `instance` (string, optional, nullable)

## Types

### DependentInfoResponse

- `associated_person_id` (string, required) — The associated person ID. Prefixed with `ap_`.
- `status` (enum, required) — The status of this dependent in the dependents management intent.
  - Allowed values: `pending_confirmation`, `action_required`, `ineligible`, `processing`, `restricted`, `ready`
- `coverage_selections` (list of PlanCoverageOptionSelectionResponse, optional, nullable) — Coverage option selections for this dependent. Populated when member-scoped selections have been provided.
- `requirement_id` (string, optional, nullable) — The adaptive requirement ID for this dependent. Populated when the dependent has an open adaptive requirement (status is `action_required`). Prefixed with `ar_`.

### PlanWithPricingResponse

- `id` (string, required) — Unique identifier for the plan. Prefixed with `pl_`.
- `name` (string, required) — The name of the plan.
- `description` (string, required) — Description of the plan.
- `pricing` (HealthPlanPricingResponse, required) — Pricing information for the plan.

### DisclosureResponse

- `category` (enum, required) — The category of the disclosure.
  - Allowed values: `regulatory`, `provider`, `intermediary`
- `type` (enum, required) — The specific type of disclosure within its category.
  - Allowed values: `intermediary_role`, `intermediary_commission`, `underwriter_disclaimer`, `anti_selection_notice`, `statement_of_needs`, `product_information`, `pre_existing_conditions`, `statutory_warning`, `privacy_policy`, `terms_of_business`
- `text` (string, required) — The disclosure statement text. It may contain `{token}` placeholders, each of which has exactly one entry in `links` and must be rendered as an anchor to that link. A disclosure with no links contains no placeholders, so plain text stays plain text.
- `links` (list of DisclosureLinkResponse, required) — The documents `text` names, one per placeholder it carries. Empty for a disclosure that is text only.

### PlanCoverageResponse

- `id` (string, required) — Unique identifier for the coverage selection. Prefixed with `pc_`.
- `name` (string, required) — Title for this coverage selection. Typically used as the display heading.
- `scope` (enum, required) — Scope of selection for this coverage selection: `group_policy` (employer selects for the group), `policy` (per-policy selection), or `member` (individual member selects).
  - Allowed values: `group_policy`, `policy`, `member`
- `input_type` (enum, required) — Describes whether this input allows selecting a single option or multiple options.
  - Allowed values: `single_select`, `multi_select`
- `required` (boolean, required) — Whether a selection is mandatory.
- `options` (list of PlanCoverageOptionResponse, required) — Available options within this coverage selection.
- `description` (string, optional, nullable) — Full description of this coverage selection.
- `min_selections` (integer, optional, nullable) — Minimum required selections (multi-select only).
- `max_selections` (integer, optional, nullable) — Maximum allowed selections (multi-select only).
- `sort_order` (integer, optional, nullable) — Display ordering hint.
- `group_label` (string, optional, nullable) — Optional grouping label for UI rendering. Indicates which coverage selections are best presented together from a UX standpoint.

### DependentsManagementIntentActionRequiredResponse

- `code` (enum, required) — The action code indicating what action is required.
  - Allowed values: `remove_restricted_or_ineligible_dependents`
- `reason` (string, required) — Brief reason for the required action.
- `reason_description` (string, required) — Detailed description of the required action. This is intended to be understandable by the end user.
- `due_by` (datetime, required) — The deadline by which the action must be completed. The day is included (i.e. the action can be completed any time during this day in the user's local time).

### PlanCoverageOptionSelectionResponse

- `configuration_id` (string, required) — Configuration ID (prefixed with `pc_`).
- `options` (list of SelectedOptionResponse, required) — Selected options.

### HealthPlanPricingResponse

- `type` (enum, required) — Type of pricing structure
  - Allowed values: `per_member`, `tier_based`
- `per_member` (PerMemberPricingResponse, optional) — Per-member pricing details (populated when type is 'per_member').
- `tier_based` (TierBasedPricingResponse, optional) — Tier-based pricing details (populated when type is 'tier_based').

### DisclosureLinkResponse

- `token` (string, required) — The placeholder this link fills. It appears in the disclosure's `text` wrapped in braces, as `{token}`, and matches `^[a-z][a-z0-9_]*$`. Tokens are unique within one disclosure, and every token in the text has exactly one link here.
- `type` (enum, required) — What kind of document this is, for reporting and audit. The token is derived from it, so the two always agree; this is the value to branch on rather than matching the token as a string.
  - Allowed values: `intermediary_role`, `intermediary_commission`, `underwriter_disclaimer`, `anti_selection_notice`, `statement_of_needs`, `product_information`, `pre_existing_conditions`, `statutory_warning`, `privacy_policy`, `terms_of_business`
- `label` (string, required) — The anchor text to display in place of the token.
- `url` (string, required) — Absolute HTTPS URL of the document.
- `version` (string, required) — Version of the document at the URL, so a record of what was shown can name the exact document the customer could have read.

### PlanCoverageOptionResponse

- `id` (string, required) — Unique identifier for this coverage option. Prefixed with `pco_`.
- `name` (string, required) — Display name for this coverage option.
- `description` (string, optional, nullable) — Longer explanation of this coverage option.
- `learn_more_url` (string, optional, nullable) — Link to learn more about this coverage option.
- `from_price` (double, optional, nullable) — Lowest applicable monthly price for this coverage option.
- `benefits` (list of PlanCoverageOptionBenefitResponse, optional, nullable) — Benefit items included with this coverage option.
- `sub_options` (list of PlanCoverageOptionResponse, optional, nullable) — Nested sub-options available when this option is selected.
- `eligibility_criteria` (list of EmployerEligibilityCriterionResponse, optional, nullable) — Eligibility criteria that must be met to select this coverage option.

### SelectedOptionResponse

- `option_id` (string, required) — Option ID (prefixed with `pco_`).
- `sub_options` (list of SelectedOptionResponse, optional, nullable) — Selected sub-options, if applicable.

### PerMemberPricingResponse

- `currency` (enum, required) — Currency code (e.g., 'eur', 'usd').
  - Allowed values: `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`
- `member_type_pricing` (list of MemberTypePricingResponse, required) — Pricing for each member type.

### TierBasedPricingResponse

- `currency` (enum, required) — Currency code (e.g., 'eur', 'usd').
  - Allowed values: `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`
- `tiers` (list of PricingTierResponse, required) — Pricing tiers for different family compositions.

### PlanCoverageOptionBenefitResponse

- `name` (string, required) — Benefit name.
- `description` (string, optional, nullable) — Benefit description.

### EmployerEligibilityCriterionResponse

- `type` (enum, required) — The type of eligibility criterion.
  - Allowed values: `employees_count`, `members_count`, `industry_exclusions`
- `description` (string, required) — Human-readable description of the criterion.
- `employees_count` (EmployeesCountDetails, optional) — Employee count constraints. Only populated when type is `employees_count`.
- `members_count` (MembersCountDetails, optional) — Member count constraints. Only populated when type is `members_count`.
- `industry_exclusions` (IndustryExclusionsDetails, optional) — Industry exclusion details. Only populated when type is `industry_exclusions`.

### MemberTypePricingResponse

- `code` (enum, required) — Member type code.
  - Allowed values: `adult`, `young_adult`, `child`
- `display_name` (string, required) — Display name for the member type.
- `monthly_premium` (double, required) — Monthly premium amount.

### PricingTierResponse

- `code` (enum, required) — Tier code.
  - Allowed values: `single`, `couple`, `single_parent`, `family`
- `display_name` (string, required) — Display name for the tier.
- `monthly_premium` (double, required) — Monthly premium amount for this tier.
- `annual_premium` (double, required) — Annual premium amount for this tier.
- `display_dependent_requirements` (string, required) — Description of dependent requirements for this tier.

### EmployeesCountDetails

- `min` (integer, optional, nullable) — Minimum number of employees required.
- `max` (integer, optional, nullable) — Maximum number of employees allowed.

### MembersCountDetails

- `min` (integer, optional, nullable) — Minimum number of members required.
- `max` (integer, optional, nullable) — Maximum number of members allowed.

### IndustryExclusionsDetails

- `excluded_industries` (list of string, required) — List of excluded industries.

## Examples

**Response**

```json
{
  "id": "dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "parent_intent_id": "string",
  "parent_intent_type": "policy_amendment_intent",
  "status": "action_required",
  "dependents": [
    {
      "associated_person_id": "ap_3b1333d87d9d4fd6ad83ba7f6b0e951a",
      "status": "pending_confirmation",
      "coverage_selections": null,
      "requirement_id": "ar_3b1333d87d9d4fd6ad83ba7f6b0e951a"
    }
  ],
  "plan": {
    "id": "pl_3b1333d87d9d4fd6ad83ba7f6b0e951a",
    "name": "string",
    "description": "string",
    "pricing": {
      "type": "per_member",
      "per_member": null,
      "tier_based": null
    }
  },
  "disclosures": [
    {
      "category": "regulatory",
      "type": "intermediary_role",
      "text": "string",
      "links": [
        {
          "token": "string",
          "type": "intermediary_role",
          "label": "string",
          "url": "string",
          "version": "string"
        }
      ]
    }
  ],
  "object": "string",
  "coverage_options": null,
  "action_required": null
}
```

**SDK Code**

```python
import requests

url = "https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent"

headers = {"Authorization": "Bearer <apiKey>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent';
const options = {method: 'POST', headers: {Authorization: 'Bearer <apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent")
  .header("Authorization", "Bearer <apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent', [
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.kota.io/enrolment_intents/ei_3b1333d87d9d4fd6ad83ba7f6b0e951a/create_dependents_management_intent")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```