# Policy flow

Interactive content available
All ledger endpoints can be interacted with through interactive [API Registry](/apis/ledger/bundled)

After a quote has been successfully issued into a policy, the policy data as well as instalment schedule and documents can be queried. It is also possible to adjust, terminate or renew the policy.

Important
All ledger endpoints require header.

`Content-Type: application/json; charset=UTF-8`

`X-TENANT-ID: {tenant_tag}`

## Policy data

#### Summary

This request always returns the latest version of the policy (even if it has MTA applied). This allows users to access policy details, certificates, and other linked resources.

#### Business Need It Solves

This endpoint is used to:

- Ensure systems and users always have access to the most up-to-date version of a policy document.
- Supports auditability and version control by allowing retrieval of specific previous versions when needed.


#### Result of the API Call

- The response structure mirrors the Quote payload (Changing Quote data), with one key difference:
  - In the Policy response, the data is wrapped inside { data: { ... } }.
- The response includes a links object that exposes the set of available next actions on the policy. These may include:
`policy:mta` – Link to initiate a Mid-Term Adjustment.
`policy:terminate` – Link to initiate policy termination.
`policy:data-change` – Link to initiate a non-rating-impacting data change (tMTA).
`policy:renew` - Link to initiate a renewal process.
The presence of these keys indicates which actions are currently available; their absence means the corresponding action is not allowed at the moment.


#### Notes

- Always returns the most recent policy version unless a specific version is requested via the version query parameter.
- Useful in scenarios where policy updates occur mid-term and latest policy data must be reflected across systems.
- Useful to track available actions after policy issuance.


## Instalments and totals data

#### Endpoint Description

The endpoint is used to retrieve a list of invoices and installment data associated with a specific policy. It returns detailed information regarding the invoice, including the invoicing number, due date, premium, administrative fees, commissions, and payable amounts.

#### Business Need

This endpoint is essential for businesses managing insurance policies, as it allows to track invoicing and payment details tied to each policy. It provides transparency and clarity about financial obligations, helping with:

**Invoice tracking**: Retrieve detailed invoice records, including premium, admin fees, and commissions, for accurate accounting.

**Payment management**: Monitor due dates and payments outstanding (e.g., the amount marked as payable), essential for cash flow management.

**Commission overview**: View broker and MGA commissions to ensure proper payouts and accountability.

**Installment data**: Useful for policyholders and insurers alike to manage and schedule payments based on invoice due dates.

## Renew

#### Summary

The **Policy Renewal** endpoint provides the functionality to renew an existing policy. The results is in creating a renewal quote with the same data as the previous policy. After the renewal quote has been created user must refer back to original quote lifecycle to issue a new renewal policy.

This endpoint does not modify any details about the policy itself, but rather triggers the system to take the necessary steps to continue the policy's active status.

#### Business Need

The **Policy Renewal** endpoint is a critical part of the insurance management workflow. As policies near their expiration, they must be renewed to continue providing coverage for the customer.

#### Notes

**Policy ID**: The policy ID must be a valid policy that is eligible for renewal. If the policy has already been renewed or is in an expired state, the response will reflect this accordingly.

**Renewal Process**: This endpoint initiates the renewal of the policy by creating a renewal quote, but it does not automatically issue a new policy. After renewal policy is created the user needs to continue as in the initial quote flow.

**Asynchronous Process**: Depending on the system's design, the renewal may trigger a series of backend processes, such as recalculating premiums, generating documents, or updating customer records. It's recommended to check the policy status after calling this endpoint to ensure the renewal was successful.

**Response Handling**: The API does not return a detailed response upon successful renewal; however, a confirmation or status update may be available in subsequent API calls, such as checking the policy's current status or documents associated with it.

## Download document content

#### Summary

The endpoint is used to **retrieve a specific document** by its ID. This can be particularly useful for fetching generated policy documents, quotes, or other related documents once they have been created and stored in the system.

#### Business Need

This endpoint provides:

- **Access to documents** related to a policy or quote, which can be crucial for downloading or viewing finalized documents (e.g., policy PDFs, terms and conditions)
- The ability to fetch any document generated during the insurance process by its unique ID
- An easy way to integrate document retrieval into workflows (e.g., display documents in a UI or send documents via email)


#### Response

| Field | Type | Description |
|  --- | --- | --- |
| (binary file) | file | Document content (usually PDF). |
| metadata | object | Document metadata (schema unspecified). |


#### Notes

- The {id} in the URL refers to the unique document identifier, which can be obtained after document generation.
- Use this endpoint to download or view individual documents after they have been generated for a policy or quote.
- The response will return the document's metadata and provide the actual document file, usually in PDF format.