Policy 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

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.

Async Request

Summary

The endpoint is used to check the status of a request, when tracking asynchronous processes like policy issuance or document generation. The endpoint allows users to confirm whether a request has been successfully processed or is still pending. Policy creation can be a time consuming process, so to keep track of it's status this request will be polling until returns either failed or success status.

Business Need It Solves

This endpoint helps with:

• Tracking the status of requests, such as policy issuance, that might take time to process asynchronously
• Ensuring that operations are completed before moving on to the next steps (e.g., issuing a policy, retrieving documents)
• Providing a mechanism for automatic retries or user notifications when a process is still pending

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

{
  "requestId": "a202dc2a-9e32-4bb8-8c74-18c73c235129",
  "status": "success",
  "data": {
    "policyId": 286532,
    "message": "Policy issued"
  }
}

What Is the Result of the API Call?

The response provides the status of the request and associated data. Common status values include:

• success – The request was completed successfully (e.g., policy issued)
• pending – The request is still being processed
• failed – The request encountered an error

Notes

The request ID ({requestId}) can be obtained from previous actions like issuing a policy or generating documents.

The status should be polled until a final status (either success or failed) is returned. If the status is pending, retry after a brief delay.

This endpoint is helpful in asynchronous workflows where a process may take time to complete.

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.

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

{
  "data": {
    "policy": { … },
    "customer": { … },
    "agent": { … },
    "objects": { … }
  },
  "meta": {
    "status": "string",
    "version": "10",
    "schemaPath": "string"
  },
  "links": {}
}

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.

curl -i -X GET \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/customers/policies/{policyId}/custom-view/installments?code=string&documentCountry=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

{
  "data": {}
}

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.

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

[]

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)

curl -i -X GET \
  'https://ledger.docs.insly.com/_mock/apis/ledger/bundled/api/v1/ledger/documents/{id}' \
  -H 'X-TENANT-ID: {$inputs.tenant}'

Response

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.