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

# Create a new policy amendment intent

POST https://test.api.kota.io/policies/{policy_id}/policy_amendment_intents
Content-Type: application/json

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.

Reference: https://docs.kota.io/api-reference/policy-amendment-intents/create-policy-amendment-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

- `policy_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.

### Body (application/json)

This endpoint expects a CreatePolicyAmendmentIntentRequest.

- `amendment_reason` (PolicyAmendmentReasonRequest, required) — The reason for the policy amendment.
- `requested_changes` (list of PolicyAmendmentRequestedChangeRequest, required) — List of requested changes to the policy.

## Response

### 200

OK

- `id` (string, required) — Unique identifier for the policy amendment intent. Prefixed with `pai_`.
- `policy_id` (string, required) — The policy ID for which the amendment is requested. Prefixed with `p_`.
- `status` (enum, required) — Current status of the policy amendment intent.
  - Allowed values: `action_required`, `awaiting_quote`, `pending_confirmation`, `processing`, `amended`, `processing_error`, `not_undertaken`
- `amendment_reason` (PolicyAmendmentReasonResponse, required) — The reason for the policy amendment.
- `requested_changes` (list of PolicyAmendmentRequestedChangeResponse, required) — List of requested changes to the policy.
- `disclosures` (list of DisclosureResponse, required) — Disclosures associated with this intent.
- `object` (string, optional) — Object type identifier.
- `required_action` (PolicyAmendmentRequiredActionResponse, optional) — Information about the required action if the intent status is `action_required`.
- `pending_confirmation` (PolicyAmendmentPendingConfirmationResponse, optional) — Information about the pending confirmation if the intent status is `pending_confirmation`.
- `processing_error` (PolicyAmendmentProcessingErrorResponse, optional) — Information about the processing error if the intent status is `processing_error`.

## 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

### PolicyAmendmentReasonRequest

- `type` (enum, required) — The type of amendment reason.
  - Allowed values: `initial_adjustment_period`, `qualifying_life_event`
- `qualifying_life_event` (QualifyingLifeEventSupplementalInfo, optional) — Supplemental information required for qualifying life event amendments.

### PolicyAmendmentRequestedChangeRequest

- `change_type` (enum, required) — The type of change requested.
  - Allowed values: `dependents`, `cancellation`

### PolicyAmendmentReasonResponse

- `type` (enum, required) — Unique identifier of the amendment reason type.
  - Allowed values: `initial_adjustment_period`, `qualifying_life_event`
- `qualifying_life_event` (PolicyAmendmentQualifyingLifeEventResponse, optional) — Details when `type` is `qualifying_life_event`.

### PolicyAmendmentRequestedChangeResponse

- `change_type` (enum, required) — The type of change requested.
  - Allowed values: `dependents`, `cancellation`

### 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`
- `title` (string, required) — The title of the disclosure statement.
- `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.

### PolicyAmendmentRequiredActionResponse

- `code` (enum, required) — The action code indicating what action is required.
  - Allowed values: `provide_dependents_information`
- `reason` (string, required) — Brief reason for the required action.
- `reason_description` (string, required) — Detailed description of the required action.
- `due_by` (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) — Information about associated persons related to this action.

### PolicyAmendmentPendingConfirmationResponse

- `code` (enum, required) — The confirmation code indicating what confirmation is pending.
  - Allowed values: `confirm_quote`, `confirm_opt_out`, `confirm_qle`
- `reason` (string, required) — Brief reason for the pending confirmation.
- `reason_description` (string, required) — Detailed description of the pending confirmation.
- `due_by` (date, required) — The deadline by which the confirmation must be provided.
- `quote` (PolicyAmendmentQuoteResponse, optional) — The quote details for the policy amendment.
- `associated_persons` (PolicyAmendmentAssociatedPersonsResponse, optional) — Information about associated persons related to this pending confirmation.

### PolicyAmendmentProcessingErrorResponse

- `code` (enum, required) — The error code indicating why processing failed.
  - Allowed values: `provider_rejected`, `unable_to_quote`
- `reason` (string, required) — Brief reason for the processing error.
- `reason_description` (string, required) — Detailed description of the processing error.

### QualifyingLifeEventSupplementalInfo

- `event` (enum, required) — The type of qualifying life event requested.
  - Allowed values: `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`
- `event_date` (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, optional, 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`.

### PolicyAmendmentQualifyingLifeEventResponse

- `event` (enum, required) — The type of qualifying life event.
  - Allowed values: `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`
- `event_date` (date, required) — The date when the qualifying life event occurred.
- `reason` (string, optional, nullable) — Additional reason or description for the qualifying life event.

### 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.

### PolicyAmendmentAssociatedPersonsResponse

- `type` (enum, required) — The type of associated person.
  - Allowed values: `dependents`
- `dependents` (PolicyAmendmentDependentsResponse, optional) — Dependents-specific information if type is 'dependents'.

### PolicyAmendmentQuoteResponse

- `currency` (string, required) — Three-letter currency code (e.g., "EUR", "USD", "GBP") for all monetary amounts in this quote.
- `monthly` (PolicyAmendmentQuoteContributionsResponse, required) — Monthly contribution breakdown for the policy amendment.
- `term` (PolicyAmendmentQuoteContributionsResponse, required) — Total term contribution breakdown for the policy amendment.

### PolicyAmendmentDependentsResponse

- `dependents_management_intent_id` (string, optional, nullable) — Unique identifier for the dependents management intent. Prefixed with `dmi_`. Null if not yet created.
- `status` (enum, optional) — The status of the dependents management process. Null if not yet started.
  - Allowed values: `action_required`, `processing`, `completed`, `not_undertaken`

### PolicyAmendmentQuoteContributionsResponse

- `employee_contribution` (PolicyAmendmentQuoteAmountResponse, required) — Employee contribution amounts.
- `employer_contribution` (PolicyAmendmentQuoteAmountResponse, required) — Employer contribution amounts.
- `total` (PolicyAmendmentQuoteAmountResponse, required) — Total contribution amounts (sum of employee and employer).

### PolicyAmendmentQuoteAmountResponse

- `net` (double, required) — Net amount before tax.
- `tax` (double, required) — Tax amount.
- `gross` (double, required) — Gross amount (net + tax).

## Examples

**Request**

```json
{
  "amendment_reason": {
    "type": "initial_adjustment_period"
  },
  "requested_changes": [
    {
      "change_type": "dependents"
    }
  ]
}
```

**Response**

```json
{
  "id": "pai_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "policy_id": "p_3b1333d87d9d4fd6ad83ba7f6b0e951a",
  "status": "action_required",
  "amendment_reason": {
    "type": "initial_adjustment_period",
    "qualifying_life_event": null
  },
  "requested_changes": [
    {
      "change_type": "dependents"
    }
  ],
  "disclosures": [
    {
      "category": "regulatory",
      "type": "intermediary_role",
      "title": "string",
      "text": "string",
      "links": [
        {
          "token": "string",
          "type": "intermediary_role",
          "label": "string",
          "url": "string",
          "version": "string"
        }
      ]
    }
  ],
  "object": "string",
  "required_action": null,
  "pending_confirmation": null,
  "processing_error": null
}
```

**SDK Code**

```python
import requests

url = "https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents"

payload = {
    "amendment_reason": { "type": "initial_adjustment_period" },
    "requested_changes": [{ "change_type": "dependents" }]
}
headers = {
    "Authorization": "Bearer <apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <apiKey>', 'Content-Type': 'application/json'},
  body: '{"amendment_reason":{"type":"initial_adjustment_period"},"requested_changes":[{"change_type":"dependents"}]}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents"

	payload := strings.NewReader("{\n  \"amendment_reason\": {\n    \"type\": \"initial_adjustment_period\"\n  },\n  \"requested_changes\": [\n    {\n      \"change_type\": \"dependents\"\n    }\n  ]\n}")

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

	req.Header.Add("Authorization", "Bearer <apiKey>")
	req.Header.Add("Content-Type", "application/json")

	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/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amendment_reason\": {\n    \"type\": \"initial_adjustment_period\"\n  },\n  \"requested_changes\": [\n    {\n      \"change_type\": \"dependents\"\n    }\n  ]\n}"

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/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents")
  .header("Authorization", "Bearer <apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amendment_reason\": {\n    \"type\": \"initial_adjustment_period\"\n  },\n  \"requested_changes\": [\n    {\n      \"change_type\": \"dependents\"\n    }\n  ]\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents', [
  'body' => '{
  "amendment_reason": {
    "type": "initial_adjustment_period"
  },
  "requested_changes": [
    {
      "change_type": "dependents"
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"amendment_reason\": {\n    \"type\": \"initial_adjustment_period\"\n  },\n  \"requested_changes\": [\n    {\n      \"change_type\": \"dependents\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "amendment_reason": ["type": "initial_adjustment_period"],
  "requested_changes": [["change_type": "dependents"]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```