> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unyte.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Management APIs

> Faciliate and manage insurance policies

Policy Management APIs are collection of interfaces that empowers our merchants and sellers with the ability to
acquire, facilitate and manage policy processes end-to-end. At the moment, we only support a
designated category of insurance policies purchases.

* Auto insurance
* Travel insurance
* Device insurance
* Health insurance
* Personal accident insurance

### Policy Issuance

The `Policy Issuance API` otherwise known as `Policy Purchase API` is, the critical component that finalizes the purchase of an insurance policy and effectively, its issuance for that customer.
Interally there are couple of data captured each tailored according to the requirements of our providers across different categories.

**Request Fields**

| Field                    | Type     | Required | Description                                                                               |
| ------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------- |
| `intent_id`              | `String` | Yes      | Purchase intent identifier                                                                |
| `merchant_code`          | `String` | Yes      | Merchant or Partner Seller's short code                                                   |
| `additional_information` | `JSON`   | Yes      | Product-specific information required for the insurance type to facilitate this purchase. |
| `activation_metadata`    | `JSON`   | Yes      | Information metadata regarding the policy activation conditions.                          |

For full list of these breakdowns, please visit the [Definitions](./definitions) to get detailed breakdown.

### Policy Cancellation

To cancel an active insurance policy. This API is used and it captures some required data to help facilitate this process.

**Request Fields**

| Field                   | Type     | Required | Description                                                                            |
| ----------------------- | -------- | -------- | -------------------------------------------------------------------------------------- |
| `policy_id`             | `UUID`   | No       | Unique identifier of the insurance policy. Provided by us.                             |
| `policy_number`         | `String` | No       | Insurance policy number as provided by the provider.                                   |
| `cancellation_reason`   | `String` | Yes      | Customer-provided information on why they preffered to have the policy terminated.     |
| `alternative_offerings` | `JSON`   | No       | Optional alternative policies or offers suggested by the merchant before cancellation. |
| `merchant_feedback`     | `String` | No       | Optional feedback from the merchant regarding the cancellation request.                |

### Policy Renewal

Merchant are able to submit renewal request on behalf of their customer just before the policy expires. Whereas there is automatical renewal support for a few policies at point-of-purchase,
this `Policy Renewal API` only allows for renewal request after an active policy has been issued.

**Request Fields**

| Field                         | Type      | Required | Description                                                                                       |
| ----------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------- |
| `policy_id`                   | `UUID`    | No       | Unique identifier of the insurance policy. Provided by us.                                        |
| `policy_number`               | `String`  | No       | Insurance policy number as provided by the provider.                                              |
| `preffered_policy_start_date` | `Date`    | Yes      | Desired start date for the renewed policy (Format: `YYYY-MM-DD`).                                 |
| `policy_duration`             | `Integer` | Yes      | Duration of the renewed policy in days (Min.: 1, Max.: 365).                                      |
| `include_additional_coverage` | `Boolean` | No       | Whether additional coverage should be included.                                                   |
| `modify_existing_coverage`    | `Boolean` | No       | Whether to modify existing coverage. Cannot be selected along with `include_additional_coverage`. |
| `coverage_details`            | `JSON`    | No       | Required if modifying or including additional coverage                                            |
| `auto_renew`                  | `Boolean` | No       | Required if the policy should auto-renew in the future                                            |

### Errors

Errors handling details are documented seperately. See [Errors Page](./errors) for status codes and messges