Insurance

The Insurance object ties together the three participating objects and links it to insurance-specific details like premium and time span of the insurance.

An insurance get created in quote status when a POST is made on the InsurableObject to be insured e.g. like POST https://api.omocom.se/v1.3/contoso/Insurances/6b315b54-c5f4-4a4b-b85c-85d685e9d18d where the GUID is the Omocom ID of the object.

Insurance Lifetimes

By default, an insurance is signed for a short, pre-defined time, typically a couple of hours or days, and are paid in full in advance. Subscription type is said to be "one-off". Depending on the needs of a platform Omocom also offers longer insurances where payment is divided into montly installments. This category of insurances is called subscription insurances. Subscription insurances is further sub-divided into Perpetual Insurances and Time Framed Insurances.

Perpetual insurances run "until further notice", i.e. user signs up for an insurance and the insurance will be renewed and invoiced each month until the user terminates the insurance. The premium might change from one month to next, if price adjustments are necessary. Any changes will be regulated in the agreement between Omocom and the platform.

Time Framed insurances has a pre-defined end date, e.g. will run for 12 months after which time it must be renewed or it will be terminated. The premium will be set for the whole period and invoiced monthly.

Insurance

The URL to create an Insurance for an object is

POST https://api.omocom.se/v1.3/contoso/SE/Insurances/6b315b54-c5f4-4a4b-b85c-85d685e9d18d

The payload body will contain the details of the insurance, and the returned GUID will identify the insurance from this point on.

{
    "totalRent": {
    "amount": 450, 
    "currency": "SEK" 
    }, 
    "insuredAmount": {
        "amount": 6500, 
        "currency": "SEK" 
    },
    "insuranceStartDateTime": "2020-01-27T11:36:48.0000000+01:00", 
    "insuranceEndDateTime": "2020-01-28T23:59:59.0000000+01:00", 
    "counterpartHandle": "de1cc8b8-1292-4f27-4346-08d7a0931723"
}

The resulting insurance will be a "one-off" insurance as it is limited to a particular time frame, defined in advance.

Perpetual Subscription Insurance

If the insurance is to be running until explicitly terminated, the insuranceEndTime is left empty and instead an insurace of type "perpetual" will be created:

{
    "totalRent": {
        "amount": 450, 
        "currency": "SEK" 
    }, 
    "insuredAmount": {
        "amount": 6500, 
        "currency": "SEK" 
    },
    "insuranceStartDateTime": "2020-01-27T11:36:48.0000000+01:00", 
    "counterpartHandle": "de1cc8b8-1292-4f27-4346-08d7a0931723"
}

The returned object will include the monthly Premium which will be invoiced for the insurance.

Time Framed Subscription Insurance

Time Framed subscriptions will be automatically activated if it is enabled for the insurance product. If a start and end date for the insurance is provided as for a regular insurance, the premium will be divided evenly on time units in that time period, most commonly one month at the time.

The returned object will include the premium for the first period which will be invoiced for the insurance.

Depending on the agreement between Omocom and the platform a time framed subscripton might be cancelled while running using the Cancel endpoint.

Insurance Object

The URL to create an Insurance for an insurable object is

POST https://api.omocom.se/v1.3/contoso/SE/Insurances/6b315b54-c5f4-4a4b-b85c-85d685e9d18d

where the GUID is the handle to the object.

Lifecycle of an Insurance

Quote

A newly created insurance has state Quote. It will be associated with a particular counterpart for a particular time frame and will have a premium price.

For platforms using opt-in insurances the user need to accept the quote and an Accept call is made:

POST https://api.omocom.se/v1.3/contoso/SE/Insurances/cd9c4d1f-23e0-492c-9570-63919bb74ee2/accept

[]

Platforms which do not use opt-in most likely makes this call automatically.

When an insurance is accepted, it gets placed in Pending state.

Pending

A pending insurance is waiting to get activated. When the pickup of the insured object happens, an Activate call should be made:

POST https://api.omocom.se/v1.3/contoso/SE/Insurances/cd9c4d1f-23e0-492c-9570-63919bb74ee2/activate

Active

The insurance is valid while it is in Active state, which it is until an End call is made:

POST https://api.omocom.se/v1.3/contoso/SE/Insurances/cd9c4d1f-23e0-492c-9570-63919bb74ee2/end

The response to the end contains an URL to a claims form, should the insurance be needed. The platform is encouraged to present this link to the user.

Depending on conditions and terms, ending an insurance before the expected end time can result in a lower actual premium than what was originally accepted with the accept call. In such cases, the response to the end call will contain information about the original accepted premium as well as the final premium. It is the responsibility of the platform to make sure the end customer only pays the final premium.

Ended

When the insurance has ended, each party get to set a rating on the other party in percent of the top rating:

POST https://api.omocom.se/v1.3/contoso/SE/users/7fb69c96-f5c7-4037-bf47-f7a081c7fa2a/Rating?ratingPercent=80&insuranceId=cd9c4d1f-23e0-492c-9570-63919bb74ee2

If the rating scale is 0-5, rating 4 would thus mean 80 in the call.

Canceling an Insurance

A one-off insurance that has not yet reached Active state can be cancelled. This means the insurance will never be activated. The need for cancellation will mostly be relevant for platforms using the Autoactivating setup.

POST https://api.omocom.se/v1.3/contoso/SE/Insurances/7fb69c96-f5c7-4037-bf47-f7a081c7fa2a/cancel?cancellationSource=Counterpart&cancellationReason="Rental postponed due to sickness"

The cancellationSource is one of Platform, PolicyHolder or Counterpart and the reason string should indicate why the insurance was cancelled.

Cancellation of Time Framed Subscripton Insurances

Depending on conditions and terms a Time Framed subscription can be cancelled in Active state as well.

Right of Withdrawal

Depending on conditions and terms, it may be possible to cancel an insurance up to a certain number of days after activation. This is e.g. useful in scenarios where the insured item is returned to the seller and thus the insurance is no longer relevant. When this occurs, Omocom will compensate the platform the correct amount, and it is up to the platform to return the insurance premium to the end customer.

Prolonging (Extending) a Running Insurance

If the insurance product allows it, an insurance in state Active can be extended in time.

POST /v1.3/contoso/SE/Insurances/7fb69c96-f5c7-4037-bf47-f7a081c7fa2a/prolong

{
  "insuranceEndDateTime": "2021-05-25T09:28:33.295Z"
}

The above example shows an insurance product that has a fixed daily price. If the product premium is based on other transaction-specific information, that info has to be provided as well:

{
  "rentalAmount": {
    "amount": 150,
    "currency": "SEK"
  },
  "insuranceEndDateTime": "2021-05-25T09:28:33.295Z"
}

The Rental Amount (or whatever name is used in the particular setup) should normally be the added price, i.e. the additional amount added to the original insurance as a result of the prolongment.

Add-On Insurances

Depending on the agreement with Omocom, a base insurance might have offers for additional insurances, "add-on insurances". For example a rental insurance might have options to sign up for a deductible waiver insurance, or a "lost keys" insurance that user can sign up for in addition to the base insurance.

In the example below the insurances for a particular integrating platform offers two add-on insurances. The returned Insurance object in state Quote will have a property listing the optional insurances and their premiums:

{
    ... 

    "addOns": [
        {
            "type": "deductibleWaiver",
            "premium": {
                "amount": 15.000000,
                "currency": "SEK"          
            }
        },
        {
            "type": "keyLossInsurance",
            "premium": {
                "amount": 12.000000,
                "currency": "SEK"          
            }
        }
    ],

    ... 
}

As normal, the insurance has to be accepted using the /Accept endpoint, which will place the insurance in Pending state - the insurance is purchased. If the purchase should also include any add-on insurances.

POST https://api.omocom.se/v1.3/contoso/SE/Insurances/3a8225bf-d955-4426-b8cc-9a6cfe6c2233/accept 

["deductibleWaiver", "keyLossInsurance"]

The above example accepts the base insurance as well as the two optional sections. The resulting 20x response will include the total premium to be paid, in this example base insurance of 89 SEK plus the two add-on insurance premiums:

{
    "totalPremium":
    {
        "amount": 116.000000,
        "currency": "SEK"
    }
}

The /Accept can contain zero or more of the sections, and the final cost and engagement will be set up accordingly.