Kota Dependents Management Intents API
The Dependents Management Intents API from Kota — 6 operation(s) for dependents management intents.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference Associated Persons Dependents Management Intents API
version: 1.0.0
servers:
- url: https://test.api.kota.io
description: test
- url: https://api.kota.io
description: production
tags:
- name: Dependents Management Intents
paths:
/dependents_management_intents/{dependents_management_intent_id}:
get:
tags:
- Dependents Management Intents
summary: Retrieve a dependents management intent
description: Retrieves a `dependents_management_intent` object by ID.
operationId: RetrieveDependentsManagementIntent
parameters:
- name: dependents_management_intent_id
in: path
required: true
schema:
pattern: dmi_.+
type: string
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DependentsManagementIntentResponse'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/dependents_management_intents/{dependents_management_intent_id}/associated_persons_eligibility:
get:
tags:
- Dependents Management Intents
summary: Retrieve associated persons eligibility for a dependents management intent
description: Retrieves all associated persons for the employee with their eligibility status for the specific policy/plan.
operationId: GetAssociatedPersonsEligibility
parameters:
- name: dependents_management_intent_id
in: path
required: true
schema:
pattern: dmi_.+
type: string
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: page
in: query
description: The page of results to return. Defaults to 1 if not provided.
schema:
type: integer
description: The page of results to return. Defaults to 1 if not provided.
format: int32
- name: page_size
in: query
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
schema:
type: integer
description: The number of results to return per page. Defaults to 10 if not provided. Maximum value is 100.
format: int32
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AssociatedPersonEligibilityResponsePagedList'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/dependents_management_intents/{dependents_management_intent_id}/dependents:
post:
tags:
- Dependents Management Intents
summary: Add dependents to a dependents management intent
description: Adds one or more existing associated persons as dependents to a dependents management intent.
operationId: AddDependentsToDependentsManagementIntent
parameters:
- name: dependents_management_intent_id
in: path
required: true
schema:
pattern: dmi_.+
type: string
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
- 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)
schema:
type: string
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/AddDependentsRequest'
required: true
responses:
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DependentsManagementIntentResponse'
/dependents_management_intents/{dependents_management_intent_id}/dependents/{associated_person_id}:
delete:
tags:
- Dependents Management Intents
summary: Remove a dependent from a Dependents Management Intent
description: Removes a specific dependent from a Dependents Management Intent by their associated person ID. The operation returns the updated DMI state.
operationId: RemoveDependentFromDependentsManagementIntent
parameters:
- name: dependents_management_intent_id
in: path
required: true
schema:
pattern: dmi_.+
type: string
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
- name: associated_person_id
in: path
required: true
schema:
pattern: ap_.+
type: string
example: ap_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DependentsManagementIntentResponse'
/dependents_management_intents/{dependents_management_intent_id}/confirm:
post:
tags:
- Dependents Management Intents
summary: Confirm dependent list
description: Submits the finalized dependent list for processing. Call this endpoint after adding all dependents to the intent. The system validates the list and transitions the intent to `processing` status. If any dependents are marked as `ineligible` or `restricted`, they must be removed before confirmation. The parent intent's action deadline must not have passed.
operationId: ConfirmDependentsManagementIntent
parameters:
- name: dependents_management_intent_id
in: path
required: true
schema:
pattern: dmi_.+
type: string
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/dependents_management_intents/{dependents_management_intent_id}/cancel:
post:
tags:
- Dependents Management Intents
summary: Cancel the dependents management intent
description: Cancels the `dependents_management_intent` in case an employee decides not to proceed with changes to their dependents. Canceling is only allowed from `action_required` status. If the intent is already `canceled`, the operation succeeds without changes. After canceling, a new dependents management intent can be created from the parent intent.
operationId: CancelDependentsManagementIntent
parameters:
- name: dependents_management_intent_id
in: path
required: true
schema:
pattern: dmi_.+
type: string
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'400':
description: Bad Request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
schemas:
PlanWithPricingResponse:
required:
- description
- id
- name
- pricing
type: object
properties:
id:
pattern: pl_.+
type: string
description: Unique identifier for the plan. Prefixed with `pl_`.
example: pl_3b1333d87d9d4fd6ad83ba7f6b0e951a
name:
type: string
description: The name of the plan.
description:
type: string
description: Description of the plan.
pricing:
allOf:
- $ref: '#/components/schemas/PlanPricingResponse'
description: Pricing information for the plan.
additionalProperties: false
PlanCoverageOptionInputType:
enum:
- single_select
- multi_select
type: string
PlanCoverageOptionScope:
enum:
- group_policy
- policy
- member
type: string
PlanCoverageResponse:
required:
- id
- input_type
- name
- options
- required
- scope
type: object
properties:
id:
pattern: pc_.+
type: string
description: Unique identifier for the coverage selection. Prefixed with `pc_`.
example: pc_3b1333d87d9d4fd6ad83ba7f6b0e951a
name:
type: string
description: Title for this coverage selection. Typically used as the display heading.
description:
type:
- 'null'
- string
description: Full description of this coverage selection.
scope:
allOf:
- $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:
allOf:
- $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.
example: true
min_selections:
type:
- 'null'
- integer
description: Minimum required selections (multi-select only).
format: int32
max_selections:
type:
- 'null'
- integer
description: Maximum allowed selections (multi-select only).
format: int32
sort_order:
type:
- 'null'
- integer
description: Display ordering hint.
format: int32
group_label:
type:
- 'null'
- string
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.
additionalProperties: false
PlanCoverageOptionSelectionRequest:
required:
- configuration_id
- options
type: object
properties:
configuration_id:
pattern: pc_.+
type: string
description: Configuration ID (prefixed with `pc_`).
example: pc_3b1333d87d9d4fd6ad83ba7f6b0e951a
options:
type: array
items:
$ref: '#/components/schemas/SelectedOptionRequest'
description: Selected options with optional sub-options.
additionalProperties: false
DependentsManagementIntentStatus:
enum:
- action_required
- processing
- completed
- not_undertaken
type: string
x-fern-enum:
action_required:
description: Dependents information needs to be provided.
processing:
description: Dependents are being validated and processed.
completed:
description: Dependents have been successfully processed and validated.
not_undertaken:
description: Dependents management intent has been aborted.
AssociatedPersonEligibilityResponsePagedList:
required:
- items
- page
- page_size
- total_count
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/AssociatedPersonEligibilityResponse'
description: A paginated array containing the response elements
page:
type: integer
description: The current page of the results
format: int32
example: 123
page_size:
type: integer
description: The number of results on this page. This can be different from the requested page size if the total number of results is less than the requested page size
format: int32
example: 123
total_count:
type: integer
description: The total number of elements available in the response. This is the total number of elements available across all pages, not just the current page.
format: int32
example: 123
has_next_page:
type: boolean
description: Whether there are more pages available after this page
readOnly: true
example: true
has_previous_page:
type: boolean
description: Whether there are more pages available before this page
readOnly: true
example: true
additionalProperties: false
TierBasedPricingResponse:
required:
- currency
- tiers
type: object
properties:
currency:
allOf:
- $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.
additionalProperties: false
DependentCoverageSelectionsRequest:
required:
- associated_person_id
- coverage_selections
type: object
properties:
associated_person_id:
pattern: ap_.+
type: string
description: The associated person ID this selection applies to.
example: ap_3b1333d87d9d4fd6ad83ba7f6b0e951a
coverage_selections:
type: array
items:
$ref: '#/components/schemas/PlanCoverageOptionSelectionRequest'
description: Coverage option selections for member-scoped configurations.
additionalProperties: false
SelectedOptionRequest:
required:
- option_id
type: object
properties:
option_id:
pattern: pco_.+
type: string
description: Option ID (prefixed with `pco_`).
example: pco_3b1333d87d9d4fd6ad83ba7f6b0e951a
sub_options:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/SelectedOptionRequest'
description: Sub-option selections, if applicable.
additionalProperties: false
PlanPricingResponse:
required:
- type
type: object
properties:
type:
allOf:
- $ref: '#/components/schemas/PlanPricingType'
description: Type of pricing structure
per_member:
type: 'null'
allOf:
- $ref: '#/components/schemas/PerMemberPricingResponse'
description: Per-member pricing details (populated when type is 'per_member').
tier_based:
type: 'null'
allOf:
- $ref: '#/components/schemas/TierBasedPricingResponse'
description: Tier-based pricing details (populated when type is 'tier_based').
additionalProperties: false
PlanCoverageOptionResponse:
required:
- id
- name
type: object
properties:
id:
pattern: pco_.+
type: string
description: Unique identifier for this coverage option. Prefixed with `pco_`.
example: pco_3b1333d87d9d4fd6ad83ba7f6b0e951a
name:
type: string
description: Display name for this coverage option.
description:
type:
- 'null'
- string
description: Longer explanation of this coverage option.
learn_more_url:
type:
- 'null'
- string
description: Link to learn more about this coverage option.
from_price:
type:
- 'null'
- number
description: Lowest applicable monthly price for this coverage option.
format: double
benefits:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/PlanCoverageOptionBenefitResponse'
description: Benefit items included with this coverage option.
sub_options:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/PlanCoverageOptionResponse'
description: Nested sub-options available when this option is selected.
eligibility_criteria:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/EmployerEligibilityCriterionResponse'
description: Eligibility criteria that must be met to select this coverage option.
additionalProperties: false
PlanPricingType:
enum:
- per_member
- tier_based
type: string
RelationshipType:
enum:
- spouse
- partner
- child
- other
type: string
SexAtBirth:
enum:
- male
- female
type: string
DependentsManagementIntentDependentStatus:
enum:
- pending_confirmation
- action_required
- ineligible
- processing
- restricted
- ready
type: string
MemberTypeCode:
enum:
- adult
- young_adult
- child
type: string
DisclosureType:
enum:
- intermediary_role
- intermediary_commission
- underwriter_disclaimer
- anti_selection_notice
- statement_of_needs
- product_information
- pre_existing_conditions
- statutory_warning
type: string
EmployerEligibilityCriterionType:
enum:
- employees_count
- members_count
- industry_exclusions
type: string
MembersCountDetails:
type: object
properties:
min:
type:
- 'null'
- integer
description: Minimum number of members required.
format: int32
max:
type:
- 'null'
- integer
description: Maximum number of members allowed.
format: int32
additionalProperties: false
CurrencyCode:
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
type: string
PricingTierResponse:
required:
- annual_premium
- code
- display_dependent_requirements
- display_name
- monthly_premium
type: object
properties:
code:
allOf:
- $ref: '#/components/schemas/FamilyTierCode'
description: Tier code.
display_name:
type: string
description: Display name for the tier.
monthly_premium:
type: number
description: Monthly premium amount for this tier.
format: double
example: 123.45
annual_premium:
type: number
description: Annual premium amount for this tier.
format: double
example: 123.45
display_dependent_requirements:
type: string
description: Description of dependent requirements for this tier.
additionalProperties: false
MemberTypePricingResponse:
required:
- code
- display_name
- monthly_premium
type: object
properties:
code:
allOf:
- $ref: '#/components/schemas/MemberTypeCode'
description: Member type code.
display_name:
type: string
description: Display name for the member type.
monthly_premium:
type: number
description: Monthly premium amount.
format: double
example: 123.45
additionalProperties: false
IndustryExclusionsDetails:
required:
- excluded_industries
type: object
properties:
excluded_industries:
type: array
items:
type: string
description: List of excluded industries.
additionalProperties: false
FamilyTierCode:
enum:
- single
- couple
- single_parent
- family
type: string
DependentsManagementIntentActionRequiredResponse:
required:
- code
- due_by
- reason
- reason_description
type: object
properties:
code:
allOf:
- $ref: '#/components/schemas/DependentsManagementIntentActionCode'
description: The action code indicating what action is required.
reason:
type: string
description: Brief reason for the required action.
reason_description:
type: string
description: Detailed description of the required action. This is intended to be understandable by the end user.
due_by:
type: string
description: 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).
format: date-time
example: '2024-12-01T00:00:00Z'
additionalProperties: false
AssociatedPersonEligibilityResponse:
required:
- associated_person_id
- date_of_birth
- eligibility_status
- first_name
- last_name
- relationship
- sex_at_birth
type: object
properties:
associated_person_id:
pattern: ap_.+
type: string
description: The associated person ID. Prefixed with `ap_`.
example: ap_3b1333d87d9d4fd6ad83ba7f6b0e951a
first_name:
type: string
description: First name of the associated person.
last_name:
type: string
description: Last name of the associated person.
date_of_birth:
type: string
description: Date of birth of the associated person.
format: date
example: '2024-12-01'
sex_at_birth:
allOf:
- $ref: '#/components/schemas/SexAtBirth'
description: Sex at birth of the associated person.
relationship:
allOf:
- $ref: '#/components/schemas/RelationshipType'
description: Relationship type to the employee.
eligibility_status:
allOf:
- $ref: '#/components/schemas/EligibilityStatus'
description: Eligibility status for the policy/plan.
ineligibility_reason:
type:
- 'null'
- string
description: Reason for ineligibility if status is ineligible.
object:
type: string
description: The object type
readOnly: true
additionalProperties: false
DependentsManagementIntentActionCode:
enum:
- remove_restricted_or_ineligible_dependents
type: string
x-fern-enum:
remove_restricted_or_ineligible_dependents:
description: One or more dependents are restricted or ineligible and must be removed before proceeding.
DependentInfoResponse:
required:
- associated_person_id
- status
type: object
properties:
associated_person_id:
pattern: ap_.+
type: string
description: The associated person ID. Prefixed with `ap_`.
example: ap_3b1333d87d9d4fd6ad83ba7f6b0e951a
status:
allOf:
- $ref: '#/components/schemas/DependentsManagementIntentDependentStatus'
description: The status of this dependent in the dependents management intent.
coverage_selections:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/PlanCoverageOptionSelectionResponse'
description: Coverage option selections for this dependent. Populated when member-scoped selections have been provided.
requirement_id:
type:
- 'null'
- string
description: The adaptive requirement ID for this dependent. Populated when the dependent has an open adaptive requirement (status is `pending_requirement`).
format: uuid
additionalProperties: false
ProblemDetails:
type: object
properties:
type:
type:
- 'null'
- string
title:
type:
- 'null'
- string
status:
type:
- 'null'
- integer
format: int32
detail:
type:
- 'null'
- string
instance:
type:
- 'null'
- string
additionalProperties: {}
DependentsManagementIntentResponse:
required:
- dependents
- disclosures
- id
- parent_intent_id
- parent_intent_type
- plan
- status
type: object
properties:
id:
pattern: dmi_.+
type: string
description: Unique identifier for the dependents management intent. Prefixed with `dmi_`.
example: dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a
object:
type: string
description: Object type identifier.
readOnly: true
parent_intent_id:
type: string
description: The parent intent ID (e.g. Policy Amendment Intent ID). Prefixed based on type.
parent_intent_type:
allOf:
- $ref: '#/components/schemas/DependentsManagementIntentParentType'
description: The type of parent intent.
status:
allOf:
- $ref: '#/components/schemas/DependentsManagementIntentStatus'
description: Current status of the dependents management intent.
dependents:
type: array
items:
$ref: '#/components/schemas/DependentInfoResponse'
description: List of dependents being managed.
plan:
allOf:
- $ref: '#/components/schemas/PlanWithPricingResponse'
description: Plan information including pricing details.
coverage_options:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/PlanCoverageResponse'
description: Available member-scoped coverage options for the plan. Present when the plan has member-scoped coverage configurations.
disclosures:
type: array
items:
$ref: '#/components/schemas/DisclosureResponse'
description: Disclosures associated with this intent.
action_required:
type: 'null'
allOf:
- $ref: '#/components/schemas/DependentsManagementIntentActionRequiredResponse'
description: 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).
additionalProperties: false
PlanCoverageOptionBenefitResponse:
required:
- name
type: object
properties:
name:
type: string
description: Benefit name.
description:
type:
- 'null'
- string
description: Benefit description.
additionalProperties: false
DisclosureResponse:
required:
- category
- text
- type
type: object
properties:
category:
allOf:
- $ref: '#/components/schemas/DisclosureCategory'
description: The category of the disclosure.
type:
allOf:
- $ref: '#/components/schemas/DisclosureType'
description: The specific type of disclosure within its category.
text:
type: string
description: The disclosure statement text.
additionalProperties: false
SelectedOptionResponse:
required:
- option_id
type: object
properties:
option_id:
pattern: pco_.+
type: string
description: Option ID (prefixed with `pco_`).
example: pco_3b1333d87d9d4fd6ad83ba7f6b0e951a
sub_options:
type:
- 'null'
- array
items:
$ref: '#/components/schemas/SelectedOptionResponse'
description: Selected sub-options, if applicable.
additionalProperties: false
PlanCoverageOptionSelectionResponse:
required:
- configuration_id
- options
type: object
properties:
configuration_id:
pattern: pc_.+
type: string
description: Configuration ID (prefixed with `pc_`).
example: pc_3b1333d87d9d4fd6ad83ba7f6b0e951a
options:
type: array
items:
$ref: '#/components/schemas/SelectedOptionResponse'
description: Selected options.
additionalProperties: false
EligibilityStatus:
enum:
- pending
- eligible
- ineligible
type: string
DisclosureCategory:
enum:
- regulatory
- provider
- intermediary
type: string
PerMemberPricingResponse:
required:
- currency
- member_type_pricing
type: object
properties:
currency:
allOf:
- $ref: '#/components/schemas/CurrencyCode'
description:
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kota/refs/heads/main/openapi/kota-dependents-management-intents-api-openapi.yml