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

# Retrieve a policy amendment intent

GET https://test.api.kota.io/policies/{policy_id}/policy_amendment_intents/{policy_amendment_intent_id}

Retrieves a `policy_amendment_intent` object.

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

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

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

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

**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",
      "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/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a"

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

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

print(response.json())
```

```javascript
const url = 'https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a';
const options = {method: 'GET', 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/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a"

	req, _ := http.NewRequest("GET", 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/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a")

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

request = Net::HTTP::Get.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.get("https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a")
  .header("Authorization", "Bearer <apiKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a', [
  'headers' => [
    'Authorization' => 'Bearer <apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://test.api.kota.io/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a");
var request = new RestRequest(Method.GET);
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/policies/p_3b1333d87d9d4fd6ad83ba7f6b0e951a/policy_amendment_intents/pai_3b1333d87d9d4fd6ad83ba7f6b0e951a")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
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()
```