---
title: "Create a new policy amendment intent"
method: POST
path: "/policies/{policy_id}/policy_amendment_intents"
tags: ["Policy Amendment Intents"]
---

# Create a new policy amendment intent

`POST /policies/{policy_id}/policy_amendment_intents`

Initiates a policy amendment (e.g. adding/removing dependents). The intent coordinates the amendment workflow including dependents sub-intent management, quote generation, employee confirmation, and provider processing.

## Path parameters

- `policy_id` string, required

## Headers

- `X-Platform-Id` string

## Request body

- CreatePolicyAmendmentIntentRequest
  - `amendment_reason` PolicyAmendmentReasonRequest, required
    - `type` 'initial_adjustment_period' | 'qualifying_life_event', required
    - `qualifying_life_event` QualifyingLifeEventSupplementalInfo
      - `event` 'gained_other_insurance_coverage' | 'divorce_or_legal_separation' | 'death_of_spouse_or_dependent' | 'moved_out_of_coverage_area' | 'employment_status_change_affecting_eligibility' | 'eligible_for_government_program' | 'marriage_or_civil_partnership' | 'birth_of_child' | 'adoption_of_child' | 'gained_legal_guardianship' | 'dependent_lost_other_coverage' | 'lost_legal_guardianship' | 'dependent_gained_other_coverage' | 'dependent_eligible_for_government_program' | 'dependent_aged_out' | 'dependent_student_status_change_affecting_eligibility' | 'dependent_moved_in_or_out_of_coverage_area' | 'other_change', required
      - `event_date` string, date, required — The date at which the event occured. Note: This date must be within provider guidelines, where the date is outside of those guidelines the amendment may be rejected or the effective date of the change could be amended by the provider.
      - `reason` string, nullable — A free text reason of the qualifying life event. Note: This will be shared with the insurance provider in lieu of `event` when its set to `other_change`.
  - `requested_changes` PolicyAmendmentRequestedChangeRequest[], required — List of requested changes to the policy.
    - `change_type` 'dependents' | 'cancellation', required

## Response `200`

OK

- PolicyAmendmentIntentResponse
  - `id` string, required — Unique identifier for the policy amendment intent. Prefixed with `pai_`.
  - `object` string — Object type identifier.
  - `policy_id` string, required — The policy ID for which the amendment is requested. Prefixed with `p_`.
  - `status` 'action_required' | 'awaiting_quote' | 'pending_confirmation' | 'processing' | 'amended' | 'processing_error' | 'not_undertaken', required
  - `amendment_reason` PolicyAmendmentReasonResponse, required
    - `type` 'initial_adjustment_period' | 'qualifying_life_event', required
    - `qualifying_life_event` PolicyAmendmentQualifyingLifeEventResponse
      - `event` 'gained_other_insurance_coverage' | 'divorce_or_legal_separation' | 'death_of_spouse_or_dependent' | 'moved_out_of_coverage_area' | 'employment_status_change_affecting_eligibility' | 'eligible_for_government_program' | 'marriage_or_civil_partnership' | 'birth_of_child' | 'adoption_of_child' | 'gained_legal_guardianship' | 'dependent_lost_other_coverage' | 'lost_legal_guardianship' | 'dependent_gained_other_coverage' | 'dependent_eligible_for_government_program' | 'dependent_aged_out' | 'dependent_student_status_change_affecting_eligibility' | 'dependent_moved_in_or_out_of_coverage_area' | 'other_change', required
      - `event_date` string, date, required — The date when the qualifying life event occurred.
      - `reason` string, nullable — Additional reason or description for the qualifying life event.
  - `requested_changes` PolicyAmendmentRequestedChangeResponse[], required — List of requested changes to the policy.
    - `change_type` 'dependents' | 'cancellation', required
  - `required_action` PolicyAmendmentRequiredActionResponse
    - `code` 'provide_dependents_information', required
    - `reason` string, required — Brief reason for the required action.
    - `reason_description` string, required — Detailed description of the required action.
    - `due_by` string, date, 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).
    - `associated_persons` PolicyAmendmentAssociatedPersonsResponse, required
      - `type` 'dependents', required
      - `dependents` PolicyAmendmentDependentsResponse
        - `dependents_management_intent_id` string, nullable — Unique identifier for the dependents management intent. Prefixed with `dmi_`. Null if not yet created.
        - `status` 'action_required' | 'processing' | 'completed' | 'not_undertaken'
  - `pending_confirmation` PolicyAmendmentPendingConfirmationResponse
    - `code` 'confirm_quote' | 'confirm_opt_out' | 'confirm_qle', required
    - `reason` string, required — Brief reason for the pending confirmation.
    - `reason_description` string, required — Detailed description of the pending confirmation.
    - `due_by` string, date, required — The deadline by which the confirmation must be provided.
    - `quote` PolicyAmendmentQuoteResponse
      - `currency` string, required — Three-letter currency code (e.g., "EUR", "USD", "GBP") for all monetary amounts in this quote.
      - `monthly` PolicyAmendmentQuoteContributionsResponse, required
        - `employee_contribution` PolicyAmendmentQuoteAmountResponse, required
          - `net` number, double, required — Net amount before tax.
          - `tax` number, double, required — Tax amount.
          - `gross` number, double, required — Gross amount (net + tax).
        - `employer_contribution` PolicyAmendmentQuoteAmountResponse, required
          - `net` number, double, required — Net amount before tax.
          - `tax` number, double, required — Tax amount.
          - `gross` number, double, required — Gross amount (net + tax).
        - `total` PolicyAmendmentQuoteAmountResponse, required
          - `net` number, double, required — Net amount before tax.
          - `tax` number, double, required — Tax amount.
          - `gross` number, double, required — Gross amount (net + tax).
      - `term` PolicyAmendmentQuoteContributionsResponse, required
        - `employee_contribution` PolicyAmendmentQuoteAmountResponse, required
          - `net` number, double, required — Net amount before tax.
          - `tax` number, double, required — Tax amount.
          - `gross` number, double, required — Gross amount (net + tax).
        - `employer_contribution` PolicyAmendmentQuoteAmountResponse, required
          - `net` number, double, required — Net amount before tax.
          - `tax` number, double, required — Tax amount.
          - `gross` number, double, required — Gross amount (net + tax).
        - `total` PolicyAmendmentQuoteAmountResponse, required
          - `net` number, double, required — Net amount before tax.
          - `tax` number, double, required — Tax amount.
          - `gross` number, double, required — Gross amount (net + tax).
    - `associated_persons` PolicyAmendmentAssociatedPersonsResponse
      - `type` 'dependents', required
      - `dependents` PolicyAmendmentDependentsResponse
        - `dependents_management_intent_id` string, nullable — Unique identifier for the dependents management intent. Prefixed with `dmi_`. Null if not yet created.
        - `status` 'action_required' | 'processing' | 'completed' | 'not_undertaken'
  - `processing_error` PolicyAmendmentProcessingErrorResponse
    - `code` 'provider_rejected' | 'unable_to_quote', required
    - `reason` string, required — Brief reason for the processing error.
    - `reason_description` string, required — Detailed description of the processing error.
  - `disclosures` DisclosureResponse[], required — Disclosures associated with this intent.
    - `category` 'regulatory' | 'provider' | 'intermediary', required
    - `type` 'intermediary_role' | 'intermediary_commission' | 'underwriter_disclaimer' | 'anti_selection_notice' | 'statement_of_needs' | 'product_information' | 'pre_existing_conditions' | 'statutory_warning', required
    - `text` string, required — The disclosure statement text.

## Other responses

- `400` — Bad Request
- `404` — Not Found

---

[API](https://skmtc.net/kota/apis/kota-api.md) · [All operations](https://skmtc.net/kota/apis/kota-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kota/kota-api/revisions/7b8b3ed87c96/schema)