Skip to main content

​
Policy object

A policy represents the contract between the insurer and the insured. A policy is linked to one or more customers — each with a business role — and can contain one or multiple assets. The relationship between customers and policies is many-to-many: a policy can have several customers, and a customer can be on several policies. Policies are the core object on the Korint platform. It contains many different attributes, including but not limited to: General information
  • product: the insurance product the policy belongs to
  • author: the user who created the policy
  • customers: links to the customers on the policy, each with a business role
  • assets: links to the insured assets covered by this policy
  • quote: if the policy is quoted, the currently active quote
Brokerage firm
  • brokerageFirmId: the brokerage firm that manages the policy
  • brokerageFees: the percentage breakdown of broker fees on the policy
Lifecycle
  • status: the policy status determines what actions are currently possible for that policy, and informs other operations such as billing
  • startedAt: the date at which the policy becomes or became active
  • stoppedAt: the stop date of the policy
    • stop: if the policy is stopped, more details about the stop reason
  • suspendedAt: the suspension date of the policy
Configuration
  • billing configuration: the chosen billing configuration for this policy
  • periodDuration: the length of the contract
  • externalId: product specific id, typically used for external reports
Product specific information
  • custom fields: a list of product specific attributes. For more details check out custom fields.

​
Working with policies over the API

A policy is not created on its own: POST /customers?productId=... creates the policyholder, the policy and the first branch together, and returns all three ids. PATCH /policies/{policyId} sets the contract-level values. The product’s policyFields go in the customFields array, while invoicingConfig, billingAssignment, periodDuration and name are aggregate fields sent as top-level properties. These are terms you decide rather than customer input, and a product that requires one of them for confirmation will refuse to confirm until it is set.

​
Branches

Work on a contract happens on a branch — a working copy. New business has its own branch, and each mid-term adjustment or renewal gets another. Almost every read and write is branch-scoped:
  • GET /policies/{policyId}/branches lists the branches still open, optionally as at a simulated date.
  • POST /policies/{policyId}/confirm requires a branchId.
  • Reads without the right branch return the base state, which looks like missing data rather than a wrong query — the most common cause of “my update did not save”.

​
Reading state

GET /policies/{policyId} is the signal to poll for anything that completes outside your request: a signature finishing, a first premium arriving, cover starting at the start date. Pair it with simulatedAt to ask what the contract looked like at a past date, and use whenAt on commands to record an action at a business time other than now.

​
Policy statuses

​
Conditional activation

Some products require the first payment before the policy can activate (requireFirstPaymentToActivate). For these, signing records the signature but leaves the policy in POLICY_SIGNED — it moves to POLICY_STARTED only once the first invoice is paid and the start date has been reached:
  • Paid before the start date — the policy still activates at the start date, not at the moment of payment.
  • Start date passed while unpaid — the policy is flagged awaiting first payment and stays POLICY_SIGNED; when the payment lands it activates retroactively at the original start date.
Contractual documents — attestations, green card, insurance memo — are issued as soon as the policy is signed and the first payment is received. They do not wait for the start date, so a customer who pays ahead of cover starting gets their proof of insurance immediately.
This is the policy-side counterpart of the FVA First Payment Gating, which defers the coverage declaration on the same signal.

​
Stopping a policy

When a policy is stopped, a cleanup workflow is automatically triggered to reconcile any billing differences. The system first waits for all pending payments to complete before computing the cleanup invoice. This ensures accurate reconciliation of the final billing state. Once all payments are finalized:
  • If the policy was billed in advance and the stop date falls before the end of a billing period, a cleanup invoice is generated to refund the overpaid amount
  • If there are outstanding amounts due, the cleanup invoice will charge the remaining balance
The cleanup invoice is only created if there is a difference between what has been billed and what should have been billed up to the stop date. The system will not proceed with cleanup until all in-progress payments have been resolved.

​
Internal notes

Brokers can attach firm-internal notes to a policy—context from a call, the reason behind a derogation, a hand-off to a colleague—without touching the contractual record. Notes are siloed by brokerage firm and never shown to the customer. See Comments & internal notes for how internal notes and public comments work in full.