Vave API Reference Guide

Full Policy Lifecycle

Flood Product

Vave API reference guide

Vave is an established web services platform, serving to integrate Canopius’ underwriting expertise with coverholder quote, bind and issue systems. The API provides instant access to pricing, binding, unbinding and live policy adjustment functionality for a range of insurance products.

This document describes how to use Vave API to quote, offer, bind, adjust and unbind for the Vave Flood product For a functional view of the API please refer to the accompanying “Vave API Overview”.

Complete lists of parameter values and mapping options are available in “Vave API Data Dictionary”

Vave API at a glance

Vave API is a set of HTTP-based RESTful web services that use OAuth 2.0 for authorization. API request and response bodies are formatted in JSON.

The endpoints are grouped by functionality into the following domains:

 Login – endpoints for authentication and authorization.

 Quote – endpoints supporting quote workflows: pricing a new quote option (New Business or Renewal), offering a quote, editing an existing quote, requesting and notifying a bind

 Policy – endpoints supporting bound policy workflows: pricing a mid-term adjustment option (Endorsement, Cancellation or Reinstatement), accepting an adjustment option and unbind a new policy or a policy MTA.

To get a priced quote option you need to submit the risk information to Quote/PriceNew endpoint.

Once received, a priced quote option is valid for 24 hours. To lock the price for the duration of the quote validity period (usually 30 days) you need to set the status to Offered by sending a notification to Quote/Offer endpoint. This converts a priced option to an offered quote, which can be bound before the quote validity period runs out.

To amend any risk information or pricing terms on an offered quote, use the Quote/Edit endpoint.

Binding a risk is a two-steps process First, send a message to Quote/RequestBind endpoint to get approval to proceed After the risk is bound in the coverholder system, send a notification to Quote/NotifyBind to confirm and to submit additional information about the bound policy.

Once a policy is live, a mid-term adjustment can be priced using one of the three Policy endpoints that price Endorsements, Cancellations and Reinstatements To accept a priced mid-term adjustment option, make a call to Policy/AcceptMTA.

If you want to undo a Quote/NotifyBind or a Policy/AcceptMTA use the Policy/Unbind. This is only an Admin Function and should only be used by the coverholder when they need to undo a Bind/Accept action that has been done in error (this endpoint should not be exposed to the agent/customer)

As you approach a policy’s expiry date, you can price a renewal option by calling Quote/PriceRenewal and follow the same steps to offer and bind it as described above.

Getting started

Vave API will not accept requests from unknown sources, so the first step is sending us IP ranges of your organization.

To start using Vave API you will need a username and password to authenticate your requests.

Authentication and authorization

Vave API uses OAuth 2.0 for authorization.

To gain accesstocorefunctionality, your application will need toobtain anaccesstoken bysubmittingyourusername and password to: https://vave.canopius.com/insure-dev/api/login

{

"UserName": "JohnSmith@somedomain.com", "Password": "UserPassword123!" }

Once you have the access token your application will need to send it in the HTTP Authorization header for all subsequent requests.

Please note that the access token has a lifespan of 60 minutes, and once it expires you will need to trade in your username and password for another token.

Alternatively, you can trade your refresh token for a new pair of tokens by submitting it to: https://vave.canopius.com/insure-dev/api/token

{

"RefreshToken":

"fdgeghyJ0eXfJKV1QiLCJhbGciOfds1NiIsIng1dCI6IkhsQzBSMTJza3hOWjFXUXdtak9GXzZ0XsfdSIsImtpZCI6sfzBSMTJzafF XUXdtak9GXzZ0X3RERSJ9[. . .]BBWVcjGIzJzhbqWLsQAAF3pUTwLOKJ-J9iErgIRm9dsfsdfgfdgdds" }

You are now ready to use Vave API!

Integration endpoints

API Response

Generic Response format

All Vave API response messages follow the same template Common sections returned in every response are message metadata, warnings and errors. The body of the response specific to each endpoint is returned in the Response section.

 Request metadata – contains fields for request traceability, such as RequestId and RequestDate. These are used to correlate messages between Vave and coverholder systems.

 Response – contains the body of the response, which is specific to each endpoint (see section Endpoints)

 Errors – contains errors caused by invalid data or formats, or failed business rules (such as underwriting guidelines or validating risk data)

 Warnings – containsmessages explaining why the original request could not be processed if the Response section contains a response offered by Vave API as a substitute for the failed original. An example of this is attempting to edit an expired quote and receiving a new priced option as a substitute, with a Warning message providing additional information

"RequestId": "52D927C2-1F17-4302-AAF4-79A97537419B", “

RequestDate": "2020-05-03T20:16:01.482Z", //UTC time zone.

"RequestTimeStamp": 1588533361482,

"Response": {

// this is the block where the response will be injected. },

"Warnings": [ {

"number": 1003, "title": "Quote Flow Switch", "description": "Switched from Edit Quote to New Quote.", "userInfo": "The validity period on PricingOption 1345 has expired." }, {

"number": 1004, "title": "Unable to offer sub product Flood Endorsement", "description": "Unable to offer sub product (Flood)", "userInfo": "Building value cannot be greater than $2M" }

"Errors": [{

"number": 1201, "title": "Data quality error", "description": "Invalid cover type (WaterDamage)” "userInfo": "Water damage deductible must be greater than $1k for this region." }, {

"number": 1004, "title": "Data quality error", "description": "Unable to accurately locate risk address", "userInfo": "Unable to accurately locate risk address." }]

HTTP Status and error codes

Vave API uses standard HTTP codes

200 – OK

The request is processed successfully Errors section is empty.

Warnings section is empty if a request is processed without any modifications. Warnings section contains additional informationwhen businessrulespreventthe original request from being processed and a substituteoptionisreturned instead.

400

Bad Request

The request failed because message format or data are invalid

401 – Unauthorized

The request is unauthorised. Check your credentials and refresh the access token.

422 – Unprocessable Entity

The format and syntax of the request are correct, but it failed business or validation rules. Response and Warnings sections are empty.

429

Too Many Requests

The number of requests your application is sending has exceeded the allowed limit.

500 - Internal Server Error

The request failed due to unexpected errors. For example, essential query parameters are missing from the URL, or message data is using unsupported data types.

See “Vave API Data Dictionary” for the full list of Vave error numbers and additional information.

Rate limiting and thresholds

Integration

We do not limit requests to Integration endpoints during development and testing. Some internal features of Vave API, including reaching out to 3rd party systems, will be turned off or will operate in Test mode.

When we moveto UAT phase we will enablefull functionality to allowend to end testing with realistic response times, and we may impose rate limits at that time

Production

Rate limits on Production will be agreed separately. Generally, we prefer to not restrict the number of requests, subject to terms of usage and periodic reviews.

Moving to Production

When you are ready to move to Production, you will need to request Live credentialsfor your application and update the URL to the following: https://vave.canopius.com/insure/

API Reference

The rest of this document describes how to use Vave API endpoints and how to construct request messages for quoting, editing and binding Flood insurance products.

“Calculating Premiums” section describes how to obtain different types of priced options: New Business, Renewal, pre-bind Edit and post-bind Mid-Term Adjustment/Cancellation/Reinstatement

“Offer and Bind Methods” section describes actions you perform on these priced options: Offer, Request Bind and Notify Bind/Accept MTA.

Calculating Premiums

Depending on the type of quote you want to request, submit risk information to one of these 6 endpoints:

5

6

All pricing endpointsexpect to receiveinformation about a risk, requested coverage optionsand pricing terms. These are submitted in the RiskInformation object.

A successful response from these endpoints contains calculated premium and a summary of terms and coverages. They are returned in the PricingOptionResponse object.

These core objects, described in the next section, are the base for calls to all pricing endpoints

General Quote format

RiskInformation example

This is the format of a request containing information about the risk It contains information about the customer, their property and possessions, as well as requested coverages and quote terms.

"ProductType": "FLOOD",

"InsuredName": "John Smith",

"DateOfBirth": "6976dc21ccea21520f3a041b2bdd9406bb7b4a5a",

"QuoteType": "New Business",

"PolicyType": "FLOOD",

"Currency": "USD",

"Inception": "2020-07-20T00:00:00Z",

"Expiry": "2021-07-20T00:00:00Z",

"Construction": "5050", "Occupancy": "1051", "OccupancyType": "1", "Address": {

"Street": "123 Main St", "City": "El Paso", "PostalCode": "79925", "StateCode": "TX", "Country": "US"

"Covers": [

"CoverType": "BUILDINGS", "CoverValue": 175000

"CoverType": "CONTENTS", "CoverValue": 20000, "CoverValueType": "RCV"

"Claims": [

"ClaimType": "FLOOD", "ClaimValue": 10000, "ClaimDate": "2018-09-07T00:00:00Z", "ClaimSettled": "true", "ClaimFullyRepaired": "true",

"ClaimDescription": "Flooding from water ponding in road"

"AdditionalInformation": [

"InformationType": "YEARBUILT", "InformationValue": "1974"

"InformationType": "FLOORAREA", "InformationValue": "1829"

"InformationType": "BASEMENT", "InformationValue": "0"

"InformationType": "NUMBEROFSTORIES", "InformationValue": "1"

"InformationType": "ABOVEWATER", "InformationValue": "1"

"InformationType": "NFIPPOLICY",

"InformationValue": "0"

"RequiredPricingTerms": [

"Peril": "ALL", "Terms":

"CoverType": "BUILDINGS", "Limit": 175000, "Deductible": 5000

"CoverType": "CONTENTS", "Limit": 20000, "Deductible": 5000

RiskInformation parameters

For a full list of values, see “Vave API Data Dictionary”.

PricingOptionResponse example

Below is an example of a successful priced option This object is returned in the “Response” section of the response message (see API Response)

"pricingOptions": [

"pricingOptionId": 602715, "quoteGroupId": "cb422d47-1f9d-4fd7-902d-898d95573882", "currency": "USD", "annualisedPremium": 1444.08, "premium": 1444.08, "pricingTerms": [ {

"peril": "FLOOD", "terms": [

"coverType": "BUILDINGS", "limit": 175000, "deductible": 5000, "limitPercentage": null, "deductiblePercentage": null

"coverType": "CONTENTS", "limit": 20000, "deductible": 5000, "limitPercentage": null, "deductiblePercentage": null

"peril": "STORMSURGE", "terms": [ {

"coverType": "BUILDINGS",

"limit": 175000, "deductible": 5000, "limitPercentage": null, "deductiblePercentage": null

"coverType": "CONTENTS", "limit": 20000, "deductible": 5000, "limitPercentage": null, "deductiblePercentage": null

"addOns": null, "paf": null

"pricingOptionId": 602716, "quoteGroupId": "cb422d47-1f9d-4fd7-902d-898d95573882", "currency": "USD", "annualisedPremium": 1245.11, "premium": 1245.11, "pricingTerms": [

"peril": "FLOOD", "terms": [

"coverType": "BUILDINGS", "limit": 175000, "deductible": 10000, "limitPercentage": null, "deductiblePercentage": null

"coverType": "CONTENTS", "limit": 20000, "deductible": 10000, "limitPercentage": null, "deductiblePercentage": null

"peril": "STORMSURGE", "terms": [

"coverType": "BUILDINGS", "limit": 175000, "deductible": 10000, "limitPercentage": null, "deductiblePercentage": null

"coverType": "CONTENTS", "limit": 20000,

For see “Vave API

Quote/PriceNew

Used to price New Business quotes, the request and response messages are the base RiskInformation and PricingOptionResponse objects described in section General Quote format

Quote/Edit

Used to change risk information and pricing terms on an offered quote.

When a request to Edit cannot be completed (for example a request to edit a quote outside of the quote validity period), the API may return a new priced option as an alternative. In this case the Warnings section on the main response object will clearly state that the returned quote is a new priced option, and not the edited quote that was originally requested. You may choose to use the substituted priced option, or to treat the Edit request as failed.

The Request message and parameters are identical to RiskInformation described above, with one additional field:

Quote you editing

The Response object is identical to the PricingOptionResponse, and will return a new PricingOptionID

Policy/PriceAdjustment

Used to price Mid-Term Adjustments on a live policy.

The Request message and parameters are identical to RiskInformation described above, with several additional fields:

EffectiveDate

The Response format follows PricingOptionResponse, with different objects for calculated premium returning the difference from the original policy premium. Detailed description below.

AdjustmentPricingOptionResponse example

"PricingOptionId": 111376,

"QuoteGroupId": "e2ba9c68-35a4-43ca-99c0-97c285f2e3e8",

"ValidUntil": "2020-05-15T00:00:00Z",

"Currency": "USD",

"AdjustedPolicyPremium": 1245.45,

"AnnualisedPremium": 1245.45,

"PremiumChange": -22.43,

"AnnualisedPremiumChange": -220.21, "pricingTerms": [

"peril": "FLOOD", "terms": [

"coverType": "BUILDINGS", "limit": 175000, "deductible": 5000, "limitPercentage": null, "deductiblePercentage": null

"coverType": "CONTENTS", "limit": 20000, "deductible": 5000, "limitPercentage": null,

"deductiblePercentage": null

"peril": "STORMSURGE", "terms":

"coverType": "BUILDINGS", "limit": 175000, "deductible": 5000, "limitPercentage": null, "deductiblePercentage": null

"coverType": "CONTENTS", "limit": 20000, "deductible": 5000, "limitPercentage": null, "deductiblePercentage": null

AdjustmentPricingOptionResponse object description:

Policy/PriceCancellation

Used to price a cancelation request

The Request message contains only three mandatory fields: the policy Id, the effective date of the cancellation and the cancellation reason. There are two additional optional fieldsthat can used to overridethe default earned premium calculation method If the optional fields are not populated the Vave API will determine which calculation method should apply based on the risk and effective date. An example is shown below:

"PolicyId": "274095"

"EffectiveDate": "2020-07-01T00:00:00Z",

"TransactionReason": "Sold the house",

"OverrideMethod": "MEP",

"OverrideMEP": "35.0"

The Responsemessage will containinformationaboutearnedandreturnpremiums. Asampleof responsemessage:

"PricingOptionId": "123445"

"PolicyId": "274095"

"AdjustedPolicyPremium": "161", "PremiumChange": "-299", "ValidUntil": "2020-06-15T00:00:00Z"

Policy/PriceReinstatement

This endpoint returns calculated premium for a reinstatement request.

The Request message will contain only the policy identifier and the reason for reinstatement, as shown in the example below:

"PolicyId": "274095"

"TransactionReason": " Updated CC number, collected payment "

Request parameters:

The Response message will contain information about the original policy premium, delta premium calculated for reinstatement and the date marking the validity period for this quote. A sample of response message:

“PricingOptionId”: “123445”

“PolicyId”: “274095”

“AdjustedPolicyPremium”: “390”,

“PremiumChange”: “70”

“ValidUntil”: “2020-06-15T00:00:00Z”

Response object description: