Core objects
Each object shares the following properties:
| Attribute | Description |
|---|---|
| type | The object type |
| id | A unique object identifier prefixed with the lower case object type |
| createdAt | The object creation timestamp in ISO 8601 UTC date time format |
| lastModifiedAt | The latest object edition timestamp in ISO 8601 UTC date time format |
| status | The object technical status |
Policy
The core object of our API is the Policy object, which embodies the insurance policy and holds references to all of the policy's objects.
Policy attributes
| Attribute | Description |
|---|---|
| branchType | The type of branch you are on |
| customer | Id of the customer |
| assets | Ids of all the assets belonging to the policy |
| invoices | Ids of all the invoices belonging to the policy |
| invoicingConfig | Invoicing options (Frequency, Early Payment, Reconciliation method, Timing & Spread) |
Policy statuses
| Status | Transition | Available actions |
|---|---|---|
| CREATED | initializePolicy | quotePolicy, editPolicy, createAsset |
| QUOTED | quotePolicy | confirmPolicy |
| CONFIRMED | confirmPolicy | createBranch |
| STARTED | Automatic at the earliest of asset startedAt |
Policy statuses follow this diagram:
Customer
The Customer object holds all information concerning the policy's client.
Customer attributes
| Attribute | Description |
|---|---|
| name | A human-readable name for the customer, doesn't need to be unique |
| postcode | Customer postcode |
Customer statuses
| Status | Transition | Available actions |
|---|---|---|
| CREATED | initializePolicy | editCustomer |
| CONFIRMED | confirmPolicy |
Customer statuses follow this diagram:
Asset
The Asset object holds all information pertaining to the insured objects. An Asset exists within a policy.
Asset attributes
| Attribute | Description |
|---|---|
| policyId | The id of the policy the asset is attached to |
| startedAt | The asset start date, ie the date at which the asset will be covered insurance-wise |
| stoppedAt | The asset stop date, ie the date at which the asset will no longer be covered |
| name | A human-readable name for the asset, doesn't need to be unique |
| value | The asset retail price in euros (€) |
Asset statuses
| Status | Transition | Available actions |
|---|---|---|
| CREATED | createAsset | editAsset, removeAsset, replaceAsset, |
| REMOVED | removeAsset | |
| QUOTED | quotePolicy | |
| CONFIRMED | confirmPolicy | |
| STARTED | Automatic at startedAt | |
| STOPPED | Automatic at stoppedAt |
Asset statuses follow this diagram:
Branch
It is common for insurance policies to have Mid Term Adjustments (MTA), which are adjustments made to a confirmed policy. For example, one might want to add, modify, or stop multiple assets multiple months after a policy's cover has begun.
The Korint API uses the branch object to handle this use case. Our objects are no longer editable after they becomes quoted, as any modification of these objects could lead to many side effects, including but not limited to:
- Pricing changes, and thus having to recalculate the payment schedules
- Documents having to be regenerated, such as invoices or conditions on a policy
- Checking policy state and making sure all rules are respected, such as a rule stipulating a maximum of 50 assets on a policy.
In the Korint API, a branch enables you to create different versions of your policy, apply modifications to each version, and select one to merge and apply its changes. Some caveats:
- Branch rebasing is not supported.
- Branches can only be created from the 'main' version of the policy, and not from a pending branch.
A typical workflow might look like this:
After policy creation, all commands must be performed on a branch by passing a branchId parameter in the request.
There is no limit to the number of pending branches you can have in parallel. However, once you confirm a branch, it will be merged and all other existing pending branches will be dropped !
Read models can target a specific branch in the same way. If no branchId is given when retrieving a resource, the main version will be returned by default.
Refer to Step-by-Step Guide for an example.