Quote flow

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

curl -i -X POST \
  https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/create \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '{}'

[]

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.

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.

curl -i -X GET \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{policyId}?withNotifications=true' \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

[
  {
    "data": {}
  },
  {
    "meta": null,
    "schemaPath": "policy/regular/{product}",
    "warnings": [ … ],
    "errors": [ … ]
  }
]

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.

curl -i -X GET \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/actions/{id}?longPolling=true' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

{
  "data": [
    "quote:download",
    "quote:update",
    "quote:copy",
    "quote:calculate",
    "quote:issue"
  ],
  "meta": [],
  "links": {
    "quote:changes": "https://app.beta.insly.training/api/v1/ledger/sales/policies/1/changes"
  }
}

Response

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)

curl -i -X POST \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{id}/calculate?withNotifications=true' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '{}'

[]

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

curl -i -X GET \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{id}/calculation' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

{
  "data": {
    "periodPremium": 500
  },
  "fields": [
    { … }
  ],
  "installments": [
    {}
  ]
}

Response

Send to referral

Summary

The Policy Referrals endpoint is used when a policy is flagged for further review, typically due to high-risk factors or other exceptions. This endpoint triggers the referral process, allowing the insurance platform to handle the policy accordingly, often requiring manual review by underwriters or other relevant staff.

Business Need

The Policy Referrals endpoint is an essential feature in the insurance workflow for handling policies that require further review or special attention. Insurance companies often need to refer policies for additional processing or verification when certain conditions are met (e.g., high-risk assessments, specific policy limits, or age-related conditions).

The business needs for this endpoint include:

• Enhanced Risk Management: Helps ensure that policies with elevated risks or unusual attributes are flagged for review before being issued.
• Compliance & Verification: Allows for the manual review of policies that don't automatically meet underwriting criteria.
• Operational Efficiency: Facilitates automated workflows for identifying and processing referrals without manual intervention.

curl -i -X POST \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{policyId}/referrals' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '{
    "comment": "Reason of sending quote to referral"
  }'

Request Payload

The request payload for this endpoint typically involves providing a comment that accompanies the referral. The comment is used to clarify the reason for the referral, which helps the team handling the referral understand the context of the referral decision.

Required Fields:

• comment (required): A message describing the reason for the referral. This could be related to issues like customer age, policy duration, or other special conditions that require manual review.

Response

As a result of a successfully completed request the status of 204 No Content is returned

Notes

• Referral Status: This field will change to "in-manual-referral" once the referral is processed.

• No Further Actions: The referral process will block certain actions on the policy, such as issuing or confirming, until the review is complete.

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

curl -i -X POST \
  https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/1/generated-documents \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

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.

curl -i -X POST \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{policyId}/bind' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '{}'

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.

Instalment schedule

Business Need

This endpoint is used to retrieve the payment installment schedule for a specific insurance policy (identified by the quote ID).

It addresses the business need of:

• Providing transparency to customers or systems about how and when payments (premiums) will be due for a given policy.
• Supporting billing systems by supplying them with structured, dated payment data.
• Enabling customer service or frontend applications to display installment plans clearly to users.

When to Use It

• After a quote has been created and before or after a policy is activated.
• When you need to present or validate the expected future payments for a policy.
• During customer onboarding or billing planning stages.

curl -i -X GET \
  https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/123/installments-schedule \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

{
  "instalments": [
    { … }
  ]
}

Customer decline

Summary

The Customer Decline endpoint is used when a customer decides to decline a quote. This action is permanent, and the policy will never be issued based on the current quote. By marking the quote as declined, the system can track this decision and store the reason for later reporting.

This endpoint ensures that all quotes, whether accepted or declined, are properly documented for both business operations and customer analytics.

Business Need

The Customer Decline endpoint serves a critical function in the insurance quote management process. It is used when a customer decides not to move forward with a specific quote, and as a result, the policy will never be issued from that particular quote.

The main business need for this endpoint includes:

• Accurate Tracking: Captures customer decisions, ensuring accurate tracking of quote rejections.
• Statistics & Reporting: Collects data on why quotes were declined, providing valuable insights into customer preferences and reasons for rejection.
• Operational Clarity: Marks the quote as declined and prevents further actions, streamlining the workflow and ensuring no further resources are spent on a quote that will not convert.

curl -i -X POST \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{policyId}/decline' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '[
    {
      "reason": "predefined decline reasons"
    },
    {
      "declinedAt": "“YYYY-MM-DD\""
    }
  ]'

No Further Actions: Once the quote is marked as declined, no further actions can be performed on the quote. It is effectively locked in the declined state.

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.

curl -i -X PUT \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{policyId}/' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '{
    "policy": {
      "dateInception": "2022-05-25",
      "dateExpiry": "2022-05-24"
    }
  }'

[]

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

curl -i -X POST \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/sales/policies/{id}/issue' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-TENANT-ID: {$inputs.tenant}' \
  -d '{}'

{
  "requestId": "64ff614a-551f-4b38-a7ba-37b7285c9562"
}

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.