Korint API Basics

The Korint API provides programmatic access and management of an insurance policy:

• Manage your assets on a first time policy or on a currently active policy,
• Always have up to date pricing and a two year payment schedule.

caution

This API is currently a demo version. As such, it is subject to breaking changes at any time and several parameters such as simulatedAt are experimental.

API structure

The Korint API is loosely organized around REST and CQRS principles.

Method	Action
GET (On a collection)	List of the collection's resources
POST (On a collection)	Creates a resource on the collection
GET (On a resource)	Retrieves the resource
POST (On a resource)	Performs a command on the resource
PATCH (On a resource)	Modifies a resource
DELETE (On a resource)	Deletes a resource

CRUD endpoint paths follow a typical REST structure, as in you will perform :

• GET /customers to retrieve the list of customers.
• GET /customers/:customer to retrieve customer data.
• POST /assets to create a new asset.
• PATCH /assets/:asset to edit asset data.
• DELETE /assets/:asset to remove an asset.

For some of our more business related operations, we add the operation at the end of the requested resource's url. So for example, you call POST /policies/:policy/confirm to confirm a policy.

note

Our read models (or queries) are strongly consistent for now, but this might change later for increased performance.

Response formats

The Korint API attempts to return a HTTP status code on every request.

Successful responses

All successful responses should return a 2xx status code.

Status code	Summary
200	Request successful with a return body.
201	Resource created.
204	Request successful with no return body.

Errors

All errors should return a 4xx or 5xx status code. A 4xx error indicates a problem with the provided information, while a 5xx error indicates a problem with the Korint servers.

Status code	Error code	Summary
400	Bad request	The request could not be understood by the server, often due to missing or unknown parameters.
401	Unauthorized	The credentials used do not give authorization on this resource.
403	Forbidden	Missing the required permissions on this resource.
404	Not found	Resource not found.
409	Conflict	This operation would lead to a conflict in the business rules, for example if attempting to modify a postcode to a non accepted value.
429	Too many requests	The API has received too many requests in a short time.
5xx	Internal server error	Something went wrong on Korint's end.

Unsuccessful responses return a JSON object containing the following information:

Key	Description
Code	A custom error code
Message	A short description about the cause of the error
Details	Context of the error

Date handling

We accept dates in ISO 8601 format. If timezone is missing from the date you send, timezone is defaulted to UTC. For example, 2023-05-23T12:00:00.00 will be processed as 2023-05-23T12:00:00.00Z.