Skip to main content

Step-by-step Guide

caution

Please note that the API is in an early version. Do not hesitate to provide feedback or to ask questions at api@korint.io

Below, we are presenting a standard happy path usage of our API.

Setup​

As Authentication is not yet implemented, you do not need any API key.

You can directly make calls with your favorite programming language or a GUI such as Postman/Insomnia.

caution

Do not forget to send the product header, which value is your product name, to perform requests on Korint API. You can use demo as a default value.

Part 1: NEW BUSINESS - From zero to a live policy​

In this first part, we will create a new customer, along with a new policy for that customer, add assets to be covered, quote the policy to obtain pricing information, and finally confirm the policy so that it becomes live.
We call this part "NEW BUSINESS".

(a) Initialize a new customer​

First initialize a customer.

POST /customers
// Returns
{
  "type": "CUSTOMER",
  "id": "customer_WWW",
  "initializedWith": {
    "branch": "branch_XXX",
    "policy": "policy_YYY",
    "customer": "customer_ZZZ"
  }
}

Under the hood, the initialization of a customer created 3 objects :

  • The customer
  • A policy that belongs to the said customer
  • A branch on which to perform commands
info

You are currently not allowed to create several branches during the NEW BUSINESS phase; it is planned in the future as it will allow to make and compare different quotes on the same policy.

(b) Set customer information​

Set the customer postcode of the customer using the editCustomer request.

PATCH /customers/{customerId}?branchId={branchId}
// Payload
{
  "SIRET": 91944490100012
}

(c) Add assets to the policy​

Add as many assets as you want using the createAsset request. You may also edit these assets with editAsset or remove them with removeAsset.

POST /assets?branchId={branchId}
// Payload
{
  "policyId": "{policyId}",
  "startedAt": "2023-08-22T12:00:00Z",
  "value": 15000, // value of the assets in cents
  "registrationNumber": "AA-123-BC" // Not required in all tenants but useful if you are interested in motor fleet
}

(d) Declare historical claims​

Declare your historical claims using the declarePolicyClaimsHistory request.

POST /policies/{policyId}/claims/history?branchId={branchId}
// Payload
{
  "claimsHistory": [
    {
      "year": "2023",
      "claimsNumber":1,
      "fleetSize": 4
    },
        {
      "year": "2022",
      "claimsNumber":0,
      "fleetSize": 3
    },
  ]
}

(e) Quote the policy​

Once you are done, you can quote the policy to get a premium for each of the assets and the policy.

POST /policies/{policyId}/quote?branchId={branchId}

To get the result of the quotation, you may retrieve the premium using the getQuote endpoint.

GET /policies/{policyId}/quote?branchId={branchId}

(f) Confirm the policy​

After having quoted the policy, you can confirm it.

POST /policies/{policyId}/confirm?branchId={branchId}

Confirming the policy will also merge the branch into the main policy. When retrieving the policy or any of its objects without a branchId parameter, you should see that the retrieved objects are confirmed and have all the details that you asked for on your branch.

For instance, you might be interested at this point to get payment schedule for this policy using the getPremiumSchedules request:

GET /policies/{policyId}/premium-schedules

Part 2: Mid Term Adjustments - Making changes on a live policy​

Once you policy has been confirmed, you might need to make some changes on that policy.
In this part, we will explore how to safely make changes, e.g. Mid Term Adjustments (MTA).

(a) Start a new MTA​

To start a new MTA, you need to create a new branch on the policy with createBranch:

POST /policies/{policyId}/branches
// Payload
{
  "branchType": "MTA",
}

Retrieve the branchId in the response, you will use it as a query parameter in all the following calls.

info You may create several branches in order to try different changes / quotes

(b) Add or Modify an Asset​

To add or modify an asset, it is the same as in the NEW BUSINESS phase.

POST /assets?branchId={branchId}

or

PATCH /assets/{assetId}?branchId={branchId}

(c) Stop an Asset​

To stop covering an asset, you need to use the edit asset endpoint and set a date on the stoppedAt field.

PATCH /assets/{assetId}?branchId={branchId}
// payload
{
  "stoppedAt": "2023-10-01T00:00:00Z",
}

(d) Quote the MTA​

Once you are done with all your changes, you need to quote the policy on your branch to get the new premium for any modified asset or new asset.

POST /policies/{policyId}/quote?branchId={branchId}

To get the result of the quotation, you may retrieve the premium using the getQuote endpoint.

GET /policies/{policyId}/quote?branchId={branchId}

(e) Confirm the MTA​

After having quoted the policy, you can confirm it.

POST /policies/{policyId}/confirm?branchId={branchId}

Confirming the branch will also merge it into the main policy. The main policy should have taken into account your NEW BUSINESS and MTA changes.

caution

If you had created several branches, all other branches will be dropped.

You might be interested at this point to get payment schedule for this policy using the getPremiumSchedules request:

GET /policies/{policyId}/premium-schedules