Policy Amendment Intents

Create a new policy amendment intent

Changed on

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.

post/policies/{policy_id}/policy_amendment_intents

Request

  • Base URL
    https://test.api.kota.io
  • URL
    https://test.api.kota.io/policies/{policy_id}/policy_amendment_intents
  • Auth
    HTTP bearer

Path parameters

policy_idstring required
Example:p_3b1333d87d9d4fd6ad83ba7f6b0e951a

Request body

Example request

{
  "amendment_reason": {
    "qualifying_life_event": {
      "event_date": "2024-12-01"
    }
  }
}

Response

OK

idstring required

Unique identifier for the policy amendment intent. Prefixed with pai_.

objectstring

Object type identifier.

policy_idstring 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

Example response

{
  "id": "pai_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "policy_id": "p_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "amendment_reason": {
    "qualifying_life_event": {
      "event_date": "2024-12-01"
    }
  },
  "required_action": {
    "due_by": "2024-12-01",
    "associated_persons": {
      "dependents": {
        "dependents_management_intent_id": "dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a"
      }
    }
  },
  "pending_confirmation": {
    "due_by": "2024-12-01",
    "quote": {
      "monthly": {
        "employee_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "employer_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "total": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        }
      },
      "term": {
        "employee_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "employer_contribution": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        },
        "total": {
          "net": 123.45,
          "tax": 123.45,
          "gross": 123.45
        }
      }
    },
    "associated_persons": {
      "dependents": {
        "dependents_management_intent_id": "dmi_3b1333d87d9d4fd6ad83ba7f6b0e951a"
      }
    }
  }
}

Changes