Seyna API (v2)

Download OpenAPI specification:Download

License: PROPRIETARY

Introduction

This is the documentation of the Seyna API v2, allowing insurance data to be exchanged with our trusted partners.

General principles

The Seyna API follows a few rules to be as easy to use as possible :

  • Every id - except for the portfolio_id - is provided to the API by the client
  • All objects are properly versioned
  • All objects can be updated at any time, as long as they are updated with an appropriate timestamp

The timestamp is the date of the information in the timeframe of the client. The accounting date is calculated from this value.

Subscription

Subscription information is split in two objects :

  • contract is the technical, up-to-date view of a subscription
  • receipt is the accounting stream linked to a single contract

In all cases, when the contract is finished, the following rules should always stand :

  • the sum of the guarantees of the receipts must equal to the guarantees of its contract
  • the cover periods of the receipts must pave the whole cover period of its contract

Single receipt

In the case of a single payment per subscription, a single receipt is emitted for the contract. In this simple case the emitted receipt has the same guarantees, start_cover_date and end_cover_date as its contract.

Single receipt

Multiple receipts

In the case of multiple apyments per subscription, multiple receipts are emitted for the contract.

Multiple receipts

The guarantees of each receipt can be calculated in different ways (per second, day, week, month...), however the values should be regular enough to make sense.

Cancellation

In the case of an early cancellation of the contract, its cover period should be adjusted to represent its new coverage, and its guarantees should be adjusted in accordance using an appropriate method, like in the case above. If a receipt has been emitted that covers past the new cover period of the contract, a new receipt should be emitted with negative guarantees to compensate for the excessive amount.

Cancellation

In the case when the whole contract is cancelled, the cover period of the contract will be collapsed to the start_cover_date.

Retractation

In the case when the contract is retracted, no negative receipt should be emitted.

Retractation

The contract and receipt cover period must be collapsed to the start_cover_date and its guarantees values must be set to zero.

Claim

Claim management information is split in two objects :

  • claim is the technical, up-to-date view of a claim
  • settlements is the accounting stream linked to a single claim

Claim life cycle

The life-cycle of a claim object is quite straitforward :

  1. a claim is open, with an outstanding value, waiting to be paid
  2. the value paid of the claim is incremented zero or more times; each time the paid value is incremented, a settlement with the corresponding value must be emitted and the outstanding value usually decreased accordingly
  3. the claim is closed and its outstanding value is set to zero.

Claim

This is a simplified case, in reality :

  • the subrogation_paid and management_paid values behave like paid
  • the subrogation_outstanding and management_outstandig values behave like outstanding

Claim value

The claim value is defined as :

  paid + outstanding
  + management_paid + management_outstanding
  - subrogation_paid - subrogation_outstanding

These are the only values that have an accounting significance. However we require a last value, called fgu_claim (for from the ground up claim), equal to the above value, but includes financial conditions, sur as : deductible, waiting period, ceiling, etc...

Integration

Authentication

In order to make a request you will need to provide an API key id and an API key secret. It must be provided in the standard HTTP Authentication header in the format Basic ${api_key_id}:${api_key_secret}

Date, time and date range

When a time is not defined for a date it defaults to T00:00:00Z. Keep this in mind when specifying date ranges (for example the start and end properties). For example if you want to specify a one year range :

  {
    "start_cover_date": "2019-01-01", // Short for "2019-01-01T00:00:00.000Z"
    "end_cover_date": "2020-01-01", // Short for "2020-01-01T00:00:00.000Z"
  }

Pagination

When retrieving a list of objects the list will provide a one-way pagination mechanism to iterate over the result. You can use the next response parameter to query the next (in a from query parameter). If there is no more page to retrieve, it will not be provided.

Page size is controlled by the limit parameter. It is an integer that can be comprised between 1 and 100 (default value is 10)

The order the items are returned can be controlled via the parameter sort, which can take the values asc or desc (default value is asc)

portfolios

Get portfolio information

Access all the information relative to the portfolio id

path Parameters
portfolio_id
required
string

The portfolio id.

Responses

Response samples

Content type
application/json
{
  • "object": "portfolio",
  • "id": "string"
}

List portfolio contracts

path Parameters
portfolio_id
required
string

The portfolio id.

query Parameters
from
string

Pagination of the response, next returned from a previous call.

limit
number [ 1 .. 100 ]

Size of the page returned.

sort
string
Default: "asc"
Enum: "asc" "desc"

Order of the result.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "string",
  • "data": [
    ],
  • "next": "string"
}

List portfolio contract versions

path Parameters
portfolio_id
required
string

The portfolio id.

query Parameters
from
string

Pagination of the response, next returned from a previous call.

limit
number [ 1 .. 100 ]

Size of the page returned.

sort
string
Default: "asc"
Enum: "asc" "desc"

Order of the result.

Responses

Response samples

Content type
application/json
{
  • "object": "list",
  • "url": "string",
  • "data": [