# Quote flow

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

Important
All ledger endpoints require header.

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

`X-TENANT-ID: {tenant_tag}`

## Create quote

#### Purpose:

This endpoint is used to create a new insurance policy quote within the system.

The `/create` endpoint solves the need for generating insurance quotes based on customer and insured item data. It provides a starting point for creating accurate quotes that can later undergo data enrichment, calculations, and adjustments before being issued as a final policy.

It supports the need for flexible policy generation in real-time, reducing the manual effort in creating insurance offers.

#### How to Use:

To create a new quote, the following steps are required:

**Authentication**: You need a valid Bearer token in the request headers for authorization.

**Quote data**: To create quote, some data should be pre-filled - the quote cannot be created empty. The fields required for quote creation are determined individually, depending on business needs.

#### Successful request

In the example provided the request and 200 response bodies are left empty. Request and response bodies for this endpoint rely greatly on the insurance product schema structure - turn to your product specific documentation for more details. This being said, all the schemas will have the `policy.id` field in the response.

| Field | Type | Description |
|  --- | --- | --- |
| policy.id | string/number | ID of the newly created preliminary quote/policy. Only field guaranteed to be useful immediately. |


Quote create endpoint response contains data which the preliminary quote was created with in addition to possible data enrichment steps already completed. In order to validate that quote creation has successfully been completed, the user needs the value of `policy.id` from this initial payload to use in the next request.

## Get quote data

#### Summary

The endpoint is used to **retrieve detailed information** about a specific policy, including its current status and relevant data. This endpoint can be particularly useful for checking the state of a policy and getting an up-to-date view of its attributes, such as coverage details, policyholder information, and any associated documents or actions.

The `withNotifications=true` query parameter ensures that the response will also include information about any pending notifications or events related to the policy.

#### Business Need It Solves

This endpoint allows users to:

- **Access detailed policy data**, including premium, coverage, and policyholder details.
- **Monitor notifications and events** related to the policy, ensuring the user is aware of any important actions (e.g., due payments, policy changes).
- Provide a **real-time view** of the policy's current state, which is essential for brokers, admins, or customers interacting with the policy.


#### Notes

The `withNotifications=true` query parameter ensures that any notifications associated with the policy (such as reminders or status updates) are included in the response.

This endpoint is useful for keeping track of policy status and understanding the next possible actions, ensuring that brokers or users are kept informed.

The response will also indicate the current state of the policy, allowing users to make decisions about whether they need to take further action (e.g., payment or renewal).

## Quote actions

#### Summary

The endpoint is used to **check the current status of background processes** and determine which actions are available for a quote or policy. This is especially important because some steps in the policy workflow are asynchronous (e.g., data enrichment, calculation), and next steps (like issuing or downloading the quote) can only proceed once those are completed.

#### Business Need It Solves

- Ensures that asynchronous processes like **data enrichment**, **validation**, or **premium calculation** have finished before continuing
- Prevents premature actions (e.g., updating quote data before data enrichment has been finalized)
- Provides a list of **available actions** the user/system can take on the quote or policy


This helps automate decision flows and build responsive UIs that only show valid operations to the end-user.

#### Response

| Field | Type | Description |
|  --- | --- | --- |
| data | array/string | Action keys currently available |
| meta | array/object | Additional metadata. |
| links | object | Related links keyed by action (e.g., "quote:changes"). |


#### Notes

Must be called after quote creation, calculation, update request.

Should be polled repeatedly until a 200 OK is received (for async processing support)

## Calculate

#### Summary

This endpoint is used to **manually trigger the recalculation** of premiums for a quote/policy. This ensures that all changes (such as optional risks, customer data, payment schedules, etc.) are correctly reflected in the updated premium values.

This endpoint is essential for **quote accuracy** and is particularly useful after:

- Quote updates
- Mid-term adjustments (MTAs)
- Optional risk modifications
- Package changes


#### Business Need

Manual recalculation:

- Guarantees the final price reflects the current data
- Enables support for complex business logic (e.g., recalculating after MTA or data changes)
- Triggers automatic notifications if `withNotifications=true` (useful for integrations and UX)


#### Request body:

- Can be empty if only recalculation is needed
- If quote data has changed, the updated payload (similar to the creation payload) can be included - check request body examples.


#### When to Use It

- After editing a quote (e.g., change in coverage, address, payment schedule)
- During Mid-term Adjustments (MTA)
- Before binding or issuing a policy (to ensure accuracy)
- After changing optional risks or switching packages


#### Notes

Recalculation is mandatory before binding or issuing to ensure pricing is correct.

If `withNotifications=true`, backend processes (e.g., quote ready signals) may be triggered for integration purposes.

## Calculation result

#### Summary

The endpoint is used to **retrieve the current total premium amount** for a quote based on the currently selected package, risks, and schedule. Unlike the `/calculate` endpoint, this does not recalculate or persist any data changes — it simply returns the **latest known premium values**.

#### Business Need

This endpoint allows consumers (frontends, brokers, integrations) to **quickly access the current premium for a given policy or quote**, which is useful for:

- Displaying premium summaries to users
- Confirming expected premium before binding
- Verifying results of previously run calculations without re-triggering business logic
- Supporting lightweight UI updates without payload processing


#### Response

| Field | Type | Description |
|  --- | --- | --- |
| data.periodPremium | number | Current total premium for the period (latest known). |
| fields | array object | Field/value details used to form the premium. |
| installments | array object | Installment breakdown used in pricing. |


## Generate quote documents

#### Summary

The endpoint is used to **generate all system documents** associated with a quote or policy. This endpoint might not be available in all flows since generating documents might require the underwriter to review and approve the quote first. It performs this task **synchronously** and immediately returns the **main document (the offer) in binary format** (typically a PDF).

#### Business Need It Solves

This endpoint provides:

- Immediate generation and download of the primary quote document (e.g., offer proposal)
- A fast, on-demand way for users or brokers to obtain quote documentation without waiting for asynchronous processing
- Document visibility during sales, quoting, or review workflows (e.g., showing the customer the official offer)


**Additional documents** might be generated in the background (but not returned here), like:

- Terms and conditions
- Product information (IPID)
- Any additional sales documents configured


#### Result of the API Call

- A **binary PDF file** representing the main document
- Other related documents (IPID, terms & conditions, etc.) can also be generated in the background, but only the **main file is returned** directly


## Bind quote

#### Summary

Binding the quote ensures that the premium and the terms of the quote are locked in and are valid for the policy issuance. Once the quote is bound, it guarantees that the policy can be issued with the same conditions and premium, even if some time has passed since the quote was created.

#### Business Need

Binding a quote is an important step because:

- **Secures the quote terms and premium** for the policyholder, preventing changes to the premium or coverage after the quote is accepted.
- **Recalculates premiums** to reflect any changes in the underlying data before binding, ensuring that the quote is valid.
- **Generates documents** necessary for the final policy issuance process.


#### Editable Fields After Binding

After a quote is bound, only a limited set of fields can still be modified. They are customisable and set according to the business needs.

#### Notes

- Request body is empty
- Binding ensures that the terms and premium of the quote will remain the same when the policy is issued. After binding, only certain fields can be updated before issuing.
- If mandatory fields are missing or invalid, a 422 HTTP error will be returned with a detailed message specifying the required information.
- In the provided request and response examples only shema-defined fields are provided for `binder`.


## Update quote data

#### Summary

This endpoint allows for updating specific fields within a quote by sending only the modified data. There’s no need to resend the full quote payload—partial updates are supported.

#### Response

The response will include the full, updated quote with any defaults applied where values were not explicitly provided.

#### Notes

- This endpoint is optimized for efficiency and minimizes payload size by supporting partial updates.
- Ensure payloads conform to the expected schema structure to avoid validation errors.
- Changes made via this endpoint do not trigger any recalculation or versioning unless explicitly tied to fields that do so.


## Issue policy

#### Summary

The endpoint is used to **issue a policy** based on the data on the quote. Issuing the policy means that it is officially created and active. This step finalizes the insurance process, turning the quote into a real, enforceable policy.

#### Business Need It Solves

Issuing a policy:

- **Finalizes the insurance coverage**, turning a temporary quote into an official, active policy.
- Generates all necessary **policy documents**, including certificates, terms, and conditions, that are provided to the policyholder.
- Triggers **administrative actions** like invoicing or payment scheduling.
- Starts the coverage period, making the insurance valid and enforceable.


This endpoint is used once a quote has been bound, ensuring that all terms and conditions are locked in and no further changes are made unless specified by a mid-term adjustment (MTA).

#### Notes

**Asynchronous Processing**: Policy issuance may not be instant. It is common to poll the status of the requestId returned by this endpoint using the /api/v1/ledger/requests/{requestId} endpoint to confirm whether the policy has been successfully issued.

**Validation**: Before issuing, the system checks that all mandatory fields are complete and correct. If any mandatory fields are missing or invalid, an error response with HTTP 422 will be returned.

**Policy Issuance Confirmation**: The policy issuance process can be asynchronous, meaning the process may take time. It is necessary to track the status of the request after triggering the issue action.