1 of 38

XCover

Integration Checklist

The following checklist describes the high level tasks that need to be completed in order to completely integrate the XCover API and begin selling insurance policies.

Common Use Cases

Outline of some frequently implemented approaches for specific industries

XCover enables in context sale of insurance to multiple industry verticals. Generally, purchase of goods and services and insurance follows a linear path: 1. Product or service selected by consumer 2. Insurance quote generated and presented to user 3. Insurance is selected and attached to the main product 4. Payment is received and then the insurance booking is confirmed with XCover The following common use cases explain in more detail how this process operates.

Events / Tickets

Event cancellation insurance or warranties - Offered via event or ticket booking platforms

Ticket and event sales services can present relevant cancellation insurance or ticket warranty policies in the event purchase booking path. Commonly, partners will integrate XCover using two key purchase process API calls: create quote and create booking. See a collection of common requests for this integration type, by contacting your CSE. Most integrations follow the below high level flow of events:

1. User browses event options and 2. Selects a event/ticket package 3. Partner platform sends a quote package payload to the create quote endpoint 4. User selects insurance options 5. User pays for tickets and insurance at checkout 6. Payment collection 7. Partner sends a booking request to the create booking endpoint 8. XCover sends confirmation email including policy details and partner sends purchase confirmation and tax invoice.

Post sale processes

Modification - Only non financial modifications are applicable for this policy type.

Cancellation - Due to the nature of event/cancellation policies cancellations are restricted in line with relevant regulations.

Opt-out process

In circumstances where a customer chooses to purchase tickets, but not the insurance offer. An opt-out request is used to notify XCover of a non-opted insurance quote. This assists with pricing and product offer data analysis and ultimately improved offers and sales results.

Travel / Accomodation

Travel Insurance such as Comprehensive, Medical, Baggage, Cancellation, Smart Delay, Insolvency, and more - Offered via Online Travel Agents and other platforms.

Online Travel Agents (OTA's) and Accommodation platforms selling flights, hotel bookings, experiences and travel packages can seamlessly present relevant travel insurance policies in the purchase booking path. Commonly, partners will integrate XCover using two key purchase process API calls: create quote and create booking. See a collection of common requests for this integration type Most integrations follow the below high level flow of events:

1. User browses travel options and; 2. Selects a travel offer 3. Partner platform sends a quote package payload to the create quote endpoint 4. User selects insurance option/s 5. User pays for travel and insurance at checkout 6. Payment collection 7. Partner sends a booking request payload to the create booking endpoint 8. XCover sends confirmation email including policy details, Partner sends purchase confirmation and tax invoice.

Post sale processes

Modification Where a partner operates a management service for booked travel services, modifications to policies may be submitted to adjust for trip length (financial adjustment), or basic updates such as address changes for a policy profile (non-financial adjustment)

Cancellation Should a partner need to facilitate travel and policy cancellation (note that this differs from trip cancellation policies, which due to their nature, may not be cancelled), the below workflow should be referenced.

Opt-out process

In circumstances where a customer chooses to purchase travel, but not the insurance offer. An opt-out request is used to notify XCover of a non-opted insurance quote. This assists with pricing and product offer data analysis and ultimately improved offers and sales results.

Property / Renters

Property related insurance products such as Renters, Landlord, etc

Commonly, partners will integrate XCover using two key purchase process API calls: create quote and create booking. Most integrations follow the below high level flow of events:

1. User goes through a property related User Experience 2. Partner platform sends a quote package payload to the create quote endpoint 3. User selects insurance option/s 4. User pays for travel and insurance at checkout 5. Payment collection 6. Partner sends a booking request payload to the create booking endpoint 7. XCover sends confirmation email including policy details, Partner sends purchase confirmation and tax invoice.

Post sale processes

Modification Changes to customer details such as name, address, or any rating factor needs to be captured in order to ensure the customer is paying the appropriate premium.

Cancellation Should a partner need to facilitate policy cancellation, the below workflow should be referenced.

Opt-out process

In circumstances where a customer chooses to purchase the anchor product or service, but not the insurance offer. An opt-out request is used to notify XCover of a non-opted insurance quote. This assists with pricing and product offer data analysis and ultimately improved offers and sales results.

Parcel / Shipping

Total Shipping Insurance - Offered to Merchants or Consumers

Shipping services and platforms offering parcel shipping, or marketplaces connected to 3rd party logistics services (3PL's) can enable the offer and or attachment of parcel insurance policies in the purchase path. Commonly, partners will integrate XCover using two key purchase process API calls: create quote and create booking. See a collection of common requests for this integration type. Many integrations follow the below high level flow of events:

1. User creates a shipment order 3. Partner platform sends a quote package payload to the create quote endpoint 4. User selects insurance option/s 5. User pays for shipment and insurance - this is often a debit of merchants shipping account wallet 6. Partner sends a booking request payload to the create booking endpoint 7. Confirmation of the coverage is presented to the user

Post sale processes

Cancellation In the event that a shipment label is not collected, and rendered void by the platform (within appropriate timeframes) the policy booking may be cancelled.

Product / Retail

Product Insurance or Warranties

Retail platforms and marketplaces can seamlessly present relevant warranty and insurance policies in the purchase path. Commonly, partners will integrate XCover using two key purchase process API calls: create quote and create booking. Depending where the offer of insurance is provided (at product page, cart page, or between as a product is added to cart), a single product quote or package quote can be used. See a collection of common requests for this integration type Most integrations follow the below high-level flow of events:

1. User browses product options and; 2. Selects a product to cart (or arrives at a product page etc.) 3. Partner platform sends a quote package payload to the create quote endpoint 4. User selects insurance option/s 5. User pays for product/s and insurance at checkout 6. Payment collection 7. Partner sends a booking request to the create booking endpoint 8. XCover sends confirmation email including policy details, Partner sends purchase confirmation and tax invoice.

In-Store CG Portal Process

For in-store purchases, sales associates can utilize the Cover Genius Portal on an iPad or similar device. The online form requires a few details about the product and some customer and payment information to protect a customer's purchase(s).

Post sale processes

Cancellation Should a partner need to facilitate policy cancellation (for example, a product return, or order cancellation), the below workflow should be referenced.

Opt-out process

In circumstances where a customer chooses to purchase products, but not the insurance offer. An opt-out request is used to notify XCover of a non-opted insurance quote. This assists with pricing and product offer data analysis and ultimately improved offers and sales results.

API Authentication

All HTTP requests sent to the XCover API must be signed with a special signature. The signature must be provided in the Authorization header. In order to generate signature partners need to have a valid API key and a secret signing key. Please note, a new signature must be generated for every request.

Generate HMAC Signature

XCover API uses HMAC-based authentication.

To authenticate API request the client application needs to perform the following steps:

Prepare request data for signing.
Sign data using one of the HMAC algorithms such as SHA1 (dprecated), SHA256 , SHA384 or SHA512 algorithms.
Encode the signature using Base64 encoding.
URL encode the result of the previous step.
Prepare Authorization header containing the Base64 and URL encoded signature string, API Key and the algorithm used, for example hmac-sha512.

Please note the date string to be signed should be in RFC 822 Section 5.1 format e.g. Thu, 04 Nov 2021 18:07:11 GMT

The date must be padded e.g. 04.

Please note the signature must be a base64 encoded strictly matching RFC 4648. Some programming languages will URL safe base64 encode which will replace the "+" and "/" characters with "-" and "_" respectively. This will cause a "Signature string does not match!" error.

Below you can see an example code implementing these steps, this code can be used as a pre-request script in Postman.

var apiKey = environment.api_key,
    apiSecret = environment.api_secret,
    date = (new Date()).toUTCString(),
    sigContent = 'date: ' + date,
    sig = CryptoJS.HmacSHA512(sigContent, apiSecret).toString(CryptoJS.enc.Base64),
    authHeader = 'Signature keyId="' + apiKey + '",algorithm="hmac-sha512",signature="' + encodeURIComponent(sig) + '"';

pm.environment.set("authHeader", authHeader);  // Authorization header
pm.environment.set("date", date);  // Date header

import requests
# Module defined below
from auth import SignatureAuth

# Prodivded by the assigned Client Solutions Engineer (CSE)
XCOVER_API_KEY = ""
XCOVER_SECRET = ""

def _apply_auth(request):
    request.headers.update(
        SignatureAuth(XCOVER_API_KEY,
                      XCOVER_SECRET).sign()
    )
    return request

session = requests.Session()
request = requests.Request('POST', url, json=payload, headers=headers)
response = session.send(_apply_auth(request.prepare()))

print(response.status_code)
    
# auth.py
"""
Authentication related module.
"""
from __future__ import unicode_literals

from base64 import b64encode
from hashlib import sha512
import hmac
from urllib.parse import quote

from datetime import datetime
from time import mktime
from wsgiref.handlers import format_date_time

def http_date():
    now = datetime.utcnow()
    return format_date_time(mktime(now.timetuple()))


class SignatureAuth:
    """Class for basic authentication support."""

    def __init__(self, key, secret):
        self._key = key
        self._secret = secret
        self._headers = None

    def create_signature(self, date):
        raw = 'date: {date}'.format(date=date)
        hashed = hmac.new(self._secret.encode('utf-8'), raw.encode('utf-8'), sha512).digest()
        return quote(b64encode(hashed), safe='')

    def build_signature(self, signature, key):
        template = ('Signature keyId="%(key)s",algorithm="hmac-sha512",'
                    'signature="%(signature)s"')

        return template % {
            'key': key,
            'signature': signature
        }

    def sign(self):
        date = http_date()
        auth = self.build_signature(signature=self.create_signature(date), key=self._key)

        return {
            'Date': date,
            'Authorization': auth,
            'X-Api-Key': self._key,
        }

using System;
using System.Web;
using System.Text;
using System.Security.Cryptography;

class Program {
    static void Main(string[] args) {
        String rfc1123DateString = DateTime.Now.ToString("R");
        String apiKey = "";
        String apiSecret = "";
	String signatureContentString = "date: " + rfc1123DateString;
	HMACSHA512 hmacsha512 = new HMACSHA512(Encoding.UTF8.GetBytes(apiSecret));
	byte[] bytes = hmacsha512.ComputeHash(Encoding.UTF8.GetBytes(signatureContentString));
	String signature = Convert.ToBase64String(bytes);
	String authHeader = "Signature keyId=\""+apiKey+"\",algorithm=\"hmac-sha512\",signature=\""+HttpUtility.UrlEncode(signatureString)+"\"";
	return authHeader;
    }
}

require "base64"
require "time"
require 'openssl'
require 'cgi/util'

def auth_header
  rfc1123_date_string = Time.now.httpdate
  api_key = ""
  api_secret = ""
  sig_content = "date: #{rfc1123_date_string}"
  sig = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'), api_secret, sig_content)
  encoded_sig = Base64.strict_encode64(sig)
  "Signature keyId=\"#{api_key}\",algorithm=\"hmac-sha512\",signature=\"#{CGI.escape(encoded_sig)}\""
end

Testing API Keys

XCover API offers provides access to staging environment that can be used to test the platform during the integration. To access the sandbox environment partners need to use testing API key that is provided by XCover team.

Idempotency Keys

Idempotency keys are unique identifiers that API clients can provide in HTTP request headers to ensure that a specific API request is not processed multiple times even if it is accidentally sent more than once. This mechanism helps maintain data consistency and prevent undesired side effects like duplicated transactions or repeating customer notifications.

Idempotency keys can be passed to most of the non-idempotent endpoints through a custom header x-idempotency-key. The value of this header should be a unique operation identifier. If the request with the same idempotency key and body has already been processed in the past the response body will be stored in a temporary storage for 48 hours and returned to all subsequent requests with 409 Conflict status code. The 409 responses can be handled by the API client as if it would be a successful response. The use of a separate response code can help API consumers identify the root cause for duplicated requests and fix the issue.

In some cases when two duplicated requests are sent within a short interval of time it is possible that a 423 Locked response code will be returned. The 423 response indicates that the API started processing the previous request, but the response was not generated yet. The API client should retry the request after a reasonable amount of time.

Find below an example of code that illustrates implementing the idempotency keys mechanism using Python's requests library.

import json
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

from logging import getLogger

logger = getLogger("xcover")

url = "https://api.xcover.com/x/partners/YOUR_PARTNER_ID/instant_booking/"

payload = json.dumps({
    # ... generated payload
})

headers = {
    # ... other required headers
    'x-idempotency-key': 'db55f986-c30c-4883-ac4f-0d2cfada6d3f'
}
retry_strategy = Retry(total=3, status_forcelist=[423, 429, 502, 503, 504], backoff_factor=5)

with requests.Session() as session:
    session.mount(url, HTTPAdapter(max_retries=retry_strategy))
    response = session.post(url, headers=headers, data=payload)
    if response.status_code in (200, 409):
        if response.status_code == 409:
            # this request is a duplicate, let's log it as a warning
            logger.warning("duplicated xcover request")

        # successfull response
        print(response.json())
    else:
        # error response
        print(response.status_code)

Rate Limits

By default, the following base API rate limits apply for all partner API keys:

Fast quote endpoint: 50 req/sec
All other endpoints: 10 req/sec (shared across all endpoints)
All testing API keys: 2 req/sec

Please, reach out to the Account Manager or Client Solution Engineer if you want to increase these limits.

Purchase Workflow Overview

The XCover platform enables efficient, flexible, and compliant offer and sale of any line of insurance within a partner web experience. Some examples include: - A public facing Online Travel Agent selling flight and accomodation packages, with related travel and cancellation insurance. - A merchant facing shipping management platform selling parcel and shipping insurance. - An ecommerce retail marketplace facilitating sales and offering warranties and or insurance policies for relevant products. In most integrations XCover policies are attached to one or more main products or services. An example of main product is a laptop purchased from an online store, flight tickets, hotel reservations, etc. Depending on the partner integration, the insurance offering is typically placed in the main product booking path. Common Request Flow: 1. Quote The initial status after the Quote Request is RECEIVED 2. Booking After customers complete the booking process and insurance premiums are collected by the partner a request to the booking endpoint must be made. A CONFIRMED INS is considered booked, sold, provisioned, and will result in a policy confirmation being submitted to the user. A simple example of such integration is demonstrated below.

Fast Quote (Optional)

Sending a Fast Quote Request

The Fast Quote endpoint is available to partners who meet specific criteria outlined by Cover Genius. Please contact your assigned Client Solutions Engineer (CSE) to discuss use of the Fast Quote endpoint.

Fast Quote request is commonly issued at product pages to display selective information about the policy which could include:

Policy Price
Product Disclosure Statement
Legal Disclaimer
Inclusions/Exclusions

Making a Fast Quote Request

Making a POST request to the fast quotes endpoint returns one or several insurance products based on the request. The request to the fast quotes endpoint is a list (as shown below). At the top level of the request, include the common fields for the quotes like currency , customer_country , customer_language along with boolean field fast quoteset as true.

Every Fast Quote request should have the minimum required information to get a quote for the specific Product. For instance, in the case of Product Insurance - we need the item category, price, name, description.

The response could have the policy details, static PDS and the price in the requested currency for the supplied parameters. This information can be presented to the customer to move them to the Booking stage.

Fast Quote is followed by Instant Booking as the next stage in the user journey where insurance is selected.

An example of fast quote request can be found below.

Request a Quote

POST https://api.xcover.com/x/partners/:partner_id/quotes/?fast_quote=1

This API call will retrieve the most relevant policies available for distribution

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner Code

Query Parameters

Name

Type

Description

fast_quote

boolean

true

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
  "currency": "AUD",
  "quotes": {
    "0": {
      "policy_start_date": "2021-03-28T10:50:20.350000+00:00",
      "policy_end_date": "2022-03-28T10:50:20.350000+00:00",
      "price": 15,
      "price_formatted": "A$15.00",
      "policy": {
        "policy_type": "product_insurance",
        "policy_name": "Full Furniture Protection",
        "policy_code": "PFUO01CG",
        "policy_version": "1d69c52e-580c-4a7b-b87c-7658f8057a86",
        "category": "furniture-insurance",
        "content": {
          "title": "Full Furniture Protection",
          "header": "Furniture Cover For Life",
          "description": "Theft, damage and expanded warranty that covers the product for life. Cancel anytime.",
          "optout_msg": "<p>.</p>",
          "inclusions": [
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ /year. Cancel anytime.",
              "description": "Full replacement if the item can’t be repaired."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ /year. Cancel anytime.",
              "description": "Cancel anytime."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ /year. Cancel anytime.",
              "description": "Covers theft."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ /year. Cancel anytime.",
              "description": "Covers repairs when your item is damaged."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ /year. Cancel anytime.",
              "description": "Covers what the manufacturer's warranty doesn’t."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ /year. Cancel anytime.",
              "description": "Extends warranty protection for the life of the policy."
            }
          ],
          "disclaimer": "<p>I am over 18 and agree to the terms of this policy. This cover is powered by XCover.com and underwritten by Pacific International Insurance Pty Ltd.</p>"
        }
      },
      "pds_url": "https://www.xcover.com/en/pds/__I6F3D__ffp-pacific/",
      "files": []
    }
  },
  "errors": {}
}

{
    "currency": "AUD",
    "customer_country": "AU",
    "customer_language": "en",
    "partner_transaction_id": "ABCD-EFGG-0000-0000",
    "request": [
        {
            "policy_type": "product_insurance",
            "policy_type_version": "1",
            "policy_start_date": "2021-03-28T10:43:56.371Z",
            "last_used_date": "2021-03-28",
            "purchase_date": "2021-03-28",
            "renewal_period": "annual",
            "retail_value": 300,
            "category": "furniture-insurance",
            "title": "Bed Base",
            "brand": "BaseWorks",
            "model": "Syntia XXL",
            "description": "Durable, king sized bed frame",
            "condition": "new"
        }
    ]
}

In the request body, you can send multiple quote requests. This means that in the case of a 200ok, you will get back a quote for each request. You only need to make one API call to get many quotes.

Displaying the Quote

Presenting the Insurance/Protection offer in the purchase path

Partners will often present an insurance offer after customers have selected a core product (such as a laptop, travel booking, event tickets, etc.). There are key components to presenting an insurance/protection offer, where 1-3 are dynamic from API response, and the items under 4 are static (provided or approved by Cover Genius CSE):

Price
Disclaimer
Policy wording link
Product name, inclusions, panel content, Trustpilot banner, and graphical elements.

Cover Genius offers a standard or customised design structure optimised for the partner specific use case (ie. Travel, Parcel, Ticket, Retail, etc.). A Travel example is presented below:

Legend: Red = Static content , Blue = API response

A Trustpilot.com rating for XCover, demonstrates reliability

B Inclusions content, taken from XCover supplied content

API Response content:

1. Price, per ticket (division of "total_price"by number of travellers/units) or full price if in "add" button ("total_price")

2. Disclaimer, taken from "content":{ "disclaimer"} field

Generally, the quote display should address:

Customer relevance - Does the quote/product presentation make sense for this purchase flow?
Compliance and regulatory requirements - Does the offer meet requirements for disclaimers, price, statements of fact, and availability of policy wording?
Marketing copy and trust - Is the offer likely to be understood and selected by the customer? Is the offer trusted/compelling?

JS based offer display

Using XCover elements, the work of coding to display quote response is removed.

A simple script is used as a wrapper for the quote request
If custom display settings are required, they may be applied using signals or taken from quote request variables (see below example).
Using Content Delivery Network (CDN), offers are displayed within the purchase flow on partner site.
Response Signals are used to determine user interaction/purchase choices.

This approach reduces the up front development effort and any ongoing growth project maintenance, allowing for streamlined launch and optimizations See more documentation for XCover Elements panel display here

Important: Most display variations are handled by quote request attributes for example the currency display could be set as Indonesian Rp (IDR):

quote_request: {
    "customer_language": "en",  //LANGUAGE: en for English, id for Bahasa
    "customer_country": "ID",   //POLICY LOCALE: AU for English, ID for Indonesia
    "currency": "IDR",          //AUD for Australia Dollar, IDR for Indonesian Rupiah

Custom Variable Display Requirements

In some cases, partners may have custom display requirements based on experience settings or customisations. An examples of custom display settings is shown below:

In the above example, circled (blue) formatting for currency symbol is selected using custom set signals (symbol). Eg:

currency_config: {
currencyDisplay: 'symbol',	//'symbol' or 'narrowSymbol'
trailingZeroDisplay: 'stripIfInteger'//'auto' or 'stripIfInteger' 
    },

In the below example, the currencyDisplay config element is set to narrowSymbol

Payment Process

How will customers pay for their policy premium?

Single Payment

Most XCover partners operate their own shopping cart, checkout, and payment collection processes. From a customer experience perspective, a single itemised purchase transaction is preferable (for example a travel booking along with the insurance policy).

Please refer to the Single Payment page for more information.

Dual Payment

In rare circumstances, Partners and XCover may agree to operate a dual payment integration approach. This results in two transactions against the same payment method of the user in quick succession. The merchant of record for the product/service remains the Partner, and the merchant of record for Insurance remains XCover. If this is your preferred integration method, please speak to your Partnerships manager or Client Solutions Engineer.

Please refer to the Dual Payment page for details on implementing this workflow.

Split Payment

In some circumstances, Partners may choose to integrate split payments (by using an approved payment provider) to split the transaction after payment collection, ie. One payment, two merchants (Partner and XCover), and two settlements (Partner and XCover). If this is your preferred integration method, please speak to your Partnerships manager or Client Solutions Engineer.

Single Payment

Overview of the payment process where the partner is the Merchant of Record (MoR)

Partners operating in markets that allow the collection of insurance premiums by non-insurance companies may use this method of premium collection. This is the most common approach for XCover partner integrations, and offers significant efficiency, process, and approval rate benefits.

If you are planning to sell insurance products to residents of the United States of America then it is likely the integration would use the unless the insurance products are travel or warranty related, in which case you might be eligible for a Travel Retailers or general warranty exemption. Please contact your assigned Client Solutions Engineer (CSE) for more information.

For partners planning to sell insurance products solely to residents of the Europe Union you might be eligible to become an Approved Representative of Cover Genius allowing you to collect premium. Otherwise you must use the . Please contact your assigned CSE for more information.

For partners planning to sell insurance products to residents elsewhere please contact your assigned CSE for more information on how to collect premiums if you wish to remain the Merchant of Record.

Optionally, Partners may choose to track the payment/checkout item using meta-data fields as indicated below, in the booking or instant booking request:

No integration steps are required for a single payment implementation approach

Dual Payment

Overview of the dual payment process where Cover Genius is the Merchant of Record

Partners that are at a minimum of PCI DSS SAQ A compliant are able to utilise the XPay API to process the insurance transaction. This will make Cover Genius the Merchant of Record (MoR).

After a customer selects the insurance product and proceeds to the checkout stage, the payment information (credit card details) must be collected and transmitted through the customer tokens endpoint.

Sending Payment Details

The XPay API uses a long lived JSON Web Token (JWT) which will be provided to you by the assigned Client Solutions Engineer (CSE).

Tokenize Card Details

POST https://api.xpay.xcover.com/customer-tokens

This API call will tokenize the customers credit card details.

Headers

Note, the /cutomer-tokens endpoint will not charge the customer, just tokenise their payment details. The customer is charged on the subsequent /bookings API call.

Making a Booking

After a successful response from the customer tokens endpoint, the partner must confirm the booking by sending a request to the booking endpoint with the customer_token_id set to the id from the previous step, this will charge the customer.

Make a Booking

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id

This API call will retrieve the most relevant policies available for distribution

Path Parameters

Headers

Once payment has been finalised policy documents, certificate of insurance will then be issued to the customer.

Booking

Booking process overview

The Booking endpoint is used to confirm the purchase of the insurance offering.

If a customer has chosen to purchase the insurance product(s) offered in the previous Quote step the customer must complete the checkout process with payment being successfully collected before proceeding with the following steps to confirm and distribute the policy.

After customers complete the booking process and insurance premiums are collected by the partner a request to the booking endpoint must be made. Validations: 1. Given the initial status after the Quote Request is RECEIVED , when a booking request is submitted, the expected status returned in response payload after a successful booking request is CONFIRMED. 2. The price field should also be validated, to confirm the final price matches the quote stage price. 3. The presence of an "errors" object in response payload indicates an important logic error in booking, that should be noted. A CONFIRMED INS is considered booked, sold, provisioned, and will result in a policy confirmation being submitted to the user.

Make a Booking

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id

The booking endpoint accepts a JSON payload against the URI containing the quote package ID returned in the quote request. The payload consists of policyholder information (most likely the same as the customer) and a list of quotes selected for purchase. the most relevant policies available for distribution

Path Parameters

Headers

Instant Booking

The Instant Booking endpoint is available to partners who meet strict criteria outlined by Cover Genius. Please contact your assigned Client Solutions Engineer (CSE) to discuss use of the Instant Booking endpoint.

If a customer has chosen to purchase the insurance product(s) offered through your platform then a call to the Instant Booking endpoint should be issued after the insurance premium has been calculated and payment has been captured.

Make an Instant Booking

POST https://api.xcover.com/x/partners/:partner_id/instant_booking/

The payload consists of information necessary to issue the policy (widely varying depending on policy type) and policyholder information

Path Parameters

Headers

Insurance Opt-Out

The Insurance opt-out workflow describes the API call that must be made in the case that XCover insurance is offered but not selected by the customer. The purpose of utilising the opt-out workflow is so Cover Genius can demonstrate conversion rate to the regulators ensuring the product and pricing is fit for purpose. It also enables XCover machine learning platform Brightwrite to deliver the optimal products at the optimal prices.

Sending Opt-Out Data

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/opt_out

The opt-out request does not require any data to be contained in the payload.

Path Parameters

Headers

Cancellation Workflow

Cancel a specific policy booking

Cancelling a policy booking is used where a user no longer requires coverage, and has contacted the partner directly to cancel this policy.

For example: Cancellation of a Product insurance policy where the product is on-sold or no longer needed. Where a refund is due, the partner (depending on method of payment collection, and policy cooling off period) may need to provide a refund to the user. This calculated pro-rata refund for the user (where applicable) is returned in the Cancellation response.

Booking Retrieval

The first step is to obtain information regarding the customers purchased insurance, this step can be skipped if you have stored all relevant information about a customers insurance booking such as INS number, Quote IDs, price paid, etc.

Retrieve a Booking

GET https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id

Retrieves a specific booking by providing the quote package ID.

Path Parameters

Headers

Booking Cancellation

Once a booking has been retrieved, check the can_be_cancelled flag is set to true in the response before issuing a cancellation request.

To ensure you refund the correct amount to the customer, it is recommended to first preview a cancellation and then confirm the cancellation once you have successfully issued the refund.

Cancel Booking

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/cancel

The booking cancel endpoint accepts a JSON payload against the URI containing the Quote Package ID returned by a /booking request. The payload consists of a list of quotes selected for cancellation and an optional reason for the cancellation.

Path Parameters

Headers

Preview a Cancellation

An optional preview flag can be set to true in the booking cancellation request payload, the response will confirm a refund amount and timeframe required before cancellation can be completed.

It is important to note key details in the response, including thecancellation_id,total_refund amount and theconfirm_beforedatetime

Preview Cancellation

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/cancel

The booking cancel endpoint accepts a JSON payload against the URI containing the Quote Package ID returned by a /booking request. The payload consists of a the preview flag set to true along with a list of quotes selected for cancellation and an optional reason for the cancellation.

Path Parameters

Headers

Confirm Cancellation

To confirm a cancellation that has been previewed a request to the following endpoint needs to be made.

Confirm Cancellation

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/confirm_cancellation

Confirm the previewed cancellation.

Path Parameters

Headers

Modification Workflow

Modifying an existing booked policy

The modification workflow is used when a customer wants to make a change to their existing policy. Examples could include; changing the date of an overseas vacation, increasing the item value or value of goods in a container, or changing the date of an event.

These changes may be possible for certain policies and can be done using the Booking Update API endpoints. These changes, if available, will cause a difference in policy price which may result in a refund or additional fee depending on the changes made.

The below diagram illustrates the API calls needed to successfully modify a customers policy.

Booking Retrieval

Retrieve a Booking

GET https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id

Retrieves a specific booking by providing the quote package ID.

Path Parameters

Headers

Booking Modification

In some circumstances a modification will not impact the premium price of a specific policy. This could be for a variety of reasons where additional information is supplied to enhance the profile of a policy, covered item, or insured party. Examples of such use cases: - Manufacturer or serial number information received after the policy booking - Product receipt or ownership verification documents or images - Address or phone number information updates for the insured

Ensure the fields you are modifying do not affect price. Speak to your assigned Client Solutions Engineer (CSE) before implementing this endpoint.

Modify Booking

PATCH https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/

Updates booking details instantly.

Path Parameters

Headers

Preview Modification - Quote for Booking Update.

A request to the quote_for_booking_update endpoint will include the details of the policy that have changed the response will include the outstanding amount to be charged or refunded.

After calling the quote_for_booking_update endpoint, and once partial refund or any additional charge is collected, a confirm update request is submitted to complete the booking update workflow.

Preview Modification

PATCH https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/quote_for_update

Generates a Quote for booking changes as specified in the request which can then be confirmed using the endpoint specified in the Response

Path Parameters

Headers

A reduction in ticket prices here is used as an example for a cause for policy value refund. See response in above section tab.

Confirm Modification

To confirm a modification that has been previewed a request to the following endpoint needs to be made.

Confirm Modification

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/confirm_update/:update_id/

Confirm the booking update and charge or refund. Optionally include the charge ID reference. Request contains no payload.

Path Parameters

Headers

Quote Request for Policies

Sending a Quote Request

The Quote request details the required information of this attached main product so that an appropriate policy quotation can be generated. The response from the Quote endpoint can be used to display information about the policy which includes:

Policy Reference ID - Unique 13 letter code for each policy (id eg. TXLDR-LH8UN-INS)
Policy Price and Applicable Taxes
Product Disclosure Statement
Legal Disclaimer
Inclusions/Exclusions
Certificate of Insurance (COI)
Benefits, Limits and Excess
Cover Amount

Making a Quote Request

Making a POST request to the quotes endpoint returns one or several insurance products based on the request. The request to the quotes endpoint is a list (as shown below). At the top level of the request, include the common fields for the quotes like currency , customer_country , customer_language .

Every Quote request should have the minimum required information to get a quote for the specific Product. For instance, in the case of Product Insurance - we need the category, price, name, description.

The response has the insurance price and details about the policy in the requested currency for the supplied parameters. This information can be presented to the customer to move them to the Booking stage.

The response has a top-level ID that is identified by a unique 13 letter alpha-numeric string ending with -INS suffix. There's also an individual ID assigned to each individual quote in the request. Both of these can be stored on the clients side to to cancel, modify and renew the policies during its lifecycle.

The initial status after the Quote Request is RECEIVED

For some integrations quote step can be skipped or quote responses can be cached, but we encourage all partners to implement price request via quote endpoint in order to enable dynamic product optimisations provided by BrightWrite platform.

An example of quote request can be found below.

Request a Quote

POST https://api.xcover.com/x/partners/:partner_id/quotes/

This API call will retrieve the most relevant policies available for distribution

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner Code

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
  "id": "TLCC8-B6YWP-INS",
  "status": "RECEIVED",
  "currency": "AUD",
  "total_price": 360.71,
  "total_price_formatted": "A$ 360.71",
  "partner_transaction_id": "ABCD-EFGG-0000-0000",
  "created_at": "2020-02-06T00:12:31.013656Z",
  "updated_at": "2020-02-06T00:12:31.013670Z",
  "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS",
  "quotes": {
    "0": {
      "id": "ca5c9839-17b3-4810-b0b1-d5b693ecef86",
      "policy_start_date": "2020-02-06T13:00:00+00:00",
      "policy_end_date": "2021-02-06T13:00:00+00:00",
      "status": "RECEIVED",
      "price": 124.85,
      "price_formatted": "A$ 124.85",
      "policy": {
        "policy_type": "product_insurance",
        "policy_name": "Full Product Protection",
        "policy_code": "PFPO05CG",
        "policy_version": "7720b62b-3e84-446a-89d3-48c83cb39384",
        "category": "electronics-insurance",
        "content": {
          "title": "Full Product Cover For Life",
          "header": "Full Product Cover For Life",
          "description": "Theft, damage and expanded warranty that covers the product for life. Cancel anytime.",
          "optout_msg": "<p>.</p>",
          "inclusions": [
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
              "description": "Full replacement if the item can’t be repaired."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
              "description": "Cancel anytime."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
              "description": "Covers theft."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
              "description": "Covers repairs when your item is damaged."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
              "description": "Covers what the manufacturer's warranty doesn’t."
            },
            {
              "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
              "description": "Extends warranty protection for the life of the policy."
            }
          ],
          "disclaimer": "<p>I am over 18 and agree to the terms of this policy. This cover is powered by XCover.com and underwritten by Pacific International Insurance Pty Ltd.</p>"
        },
        "underwriter": {
          "disclaimer": "This cover is powered by XCover and underwritten by Pacific International Insurance Pty. Ltd.",
          "name": "Pacific International Insurance Pty. Ltd."
        }
      },
      "insured": null,
      "tax": {
        "total_tax": 21.67,
        "total_amount_without_tax": 103.18,
        "total_tax_formatted": "A$ 21.67",
        "total_amount_without_tax_formatted": "A$ 103.18",
        "taxes": [
          {
            "tax_amount": 11.35,
            "tax_code": "SD",
            "tax_amount_formatted": "A$ 11.35"
          },
          {
            "tax_amount": 10.32,
            "tax_code": "GST",
            "tax_amount_formatted": "A$ 10.32"
          },
          {
            "tax_amount": 0.0,
            "tax_code": "ESL",
            "tax_amount_formatted": "A$ 0.00"
          }
        ]
      },
      "duration": "366 00:00:00",
      "benefits": [
        {
          "description": "Damage or Theft",
          "limit": 1349.76,
          "limit_policy_currency": 1349.76,
          "limit_formatted": "A$ 1349.76",
          "limit_policy_currency_formatted": "A$ 1349.76",
          "excess": 150.0,
          "excess_policy_currency": 150.0,
          "excess_formatted": "A$ 150.00",
          "excess_policy_currency_formatted": "A$ 150.00"
        },
        {
          "description": "Extended Warranty",
          "limit": 1349.76,
          "limit_policy_currency": 1349.76,
          "limit_formatted": "A$ 1349.76",
          "limit_policy_currency_formatted": "A$ 1349.76",
          "excess": 150.0,
          "excess_policy_currency": 150.0,
          "excess_formatted": "A$ 150.00",
          "excess_policy_currency_formatted": "A$ 150.00"
        }
      ],
      "commission": {
        "total_commission": 0.0,
        "total_commission_formatted": "A$ 0.00"
      },
      "created_at": "2020-02-06T00:12:30.974396Z",
      "confirmed_at": null,
      "updated_at": "2020-02-06T00:12:30.974411Z",
      "cancelled_at": null,
      "is_renewable": true,
      "cover_amount": 1349.0,
      "cover_amount_formatted": "A$ 1349.00",
      "pending_renewal": null,
      "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS?policy_type=product_insurance_v1",
      "discount_price": 124.85,
      "discount_price_formatted": "A$ 124.85",
      "discount_amount": 0.0,
      "discount_amount_formatted": "A$ 0.00"
    }
  },
  "bundle_code": null,
  "bundle_price": 360.71,
  "bundle_content": {},
  "bundle_price_formatted": "A$ 360.71",
  "bundle_discount_percent": 0.0,
  "bundle_discount_amount": 0.0,
  "bundle_discount_amount_formatted": "A$ 0.00"
}

{
    "currency": "AUD",
    "customer_country": "AU",
    "customer_language": "en",
    "partner_transaction_id": "1ef4472a-a50e-4c52-87e1-73b9ca988031",
    "request": [
        {
            "policy_type": "product_insurance",
            "policy_type_version": "2",
            "policy_start_date": "2021-01-14T18:30:00+00:00",
            "retail_value": 3799,
            "category": "Laptop",
            "title": "Apple MacBook Pro",
            "brand": "Apple",
            "model": "MacBook Pro",
            "description": "Apple Macbook Pro 16\" 2019 2.6 GHz w/ Touch Bar 512GB - Space Grey - Au Stock",
            "sku": "190199368477",
            "condition": "new"
        }
    ]
}

In the request body, you can send multiple quote requests. This means that in the case of a 201, you will get back a quote for each request. You only need to make one API call to get many quotes. The next example demonstrates this.

Multiple Quotes in Single Request

Request Multiple Quotes

POST https://api.xcover.com/x/partners/:partner_id/quotes/

An example of requesting a QuotePackage with two policies for two separate products. The first element of the Request array is a Policy for a Laptop followed by a Mobile phone policy The response under quotes key in the body is zero-indexed based on the position in the request. The first element has an index of 0 in the response, the second element has an index of 1 and so on.

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner Code

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
    "id": "TLCC8-B6YWP-INS",
    "status": "RECEIVED",
    "currency": "AUD",
    "total_price": 360.71,
    "total_price_formatted": "A$ 360.71",
    "partner_transaction_id": "ABCD-EFGG-0000-0000",
    "created_at": "2020-02-06T00:12:31.013656Z",
    "updated_at": "2020-02-06T00:12:31.013670Z",
    "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS",
    "quotes": {
        "0": {
            "id": "ca5c9839-17b3-4810-b0b1-d5b693ecef86",
            "policy_start_date": "2020-02-06T13:00:00+00:00",
            "policy_end_date": "2021-02-06T13:00:00+00:00",
            "status": "RECEIVED",
            "price": 124.85,
            "price_formatted": "A$ 124.85",
            "policy": {
                "policy_type": "product_insurance",
                "policy_name": "Full Product Protection",
                "policy_code": "PFPO05CG",
                "policy_version": "7720b62b-3e84-446a-89d3-48c83cb39384",
                "category": "electronics-insurance",
                "content": {
                    "title": "Full Product Cover For Life",
                    "header": "Full Product Cover For Life",
                    "description": "Theft, damage and expanded warranty that covers the product for life. Cancel anytime.",
                    "optout_msg": "<p>.</p>",
                    "inclusions": [
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
                            "description": "Full replacement if the item can’t be repaired."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
                            "description": "Cancel anytime."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
                            "description": "Covers theft."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
                            "description": "Covers repairs when your item is damaged."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
                            "description": "Covers what the manufacturer's warranty doesn’t."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 124.85/year. Cancel anytime.",
                            "description": "Extends warranty protection for the life of the policy."
                        }
                    ],
                    "disclaimer": "<p>I am over 18 and agree to the terms of this policy. This cover is powered by XCover.com and underwritten by Pacific International Insurance Pty Ltd.</p>"
                },
                "underwriter": {
                    "disclaimer": "This cover is powered by XCover and underwritten by Pacific International Insurance Pty. Ltd.",
                    "name": "Pacific International Insurance Pty. Ltd."
                }
            },
            "insured": null,
            "tax": {
                "total_tax": 21.67,
                "total_amount_without_tax": 103.18,
                "total_tax_formatted": "A$ 21.67",
                "total_amount_without_tax_formatted": "A$ 103.18",
                "taxes": [
                    {
                        "tax_amount": 11.35,
                        "tax_code": "SD",
                        "tax_amount_formatted": "A$ 11.35"
                    },
                    {
                        "tax_amount": 10.32,
                        "tax_code": "GST",
                        "tax_amount_formatted": "A$ 10.32"
                    },
                    {
                        "tax_amount": 0.0,
                        "tax_code": "ESL",
                        "tax_amount_formatted": "A$ 0.00"
                    }
                ]
            },
            "duration": "366 00:00:00",
            "benefits": [
                {
                    "description": "Damage or Theft",
                    "limit": 1349.76,
                    "limit_policy_currency": 1349.76,
                    "limit_formatted": "A$ 1349.76",
                    "limit_policy_currency_formatted": "A$ 1349.76",
                    "excess": 150.0,
                    "excess_policy_currency": 150.0,
                    "excess_formatted": "A$ 150.00",
                    "excess_policy_currency_formatted": "A$ 150.00"
                },
                {
                    "description": "Extended Warranty",
                    "limit": 1349.76,
                    "limit_policy_currency": 1349.76,
                    "limit_formatted": "A$ 1349.76",
                    "limit_policy_currency_formatted": "A$ 1349.76",
                    "excess": 150.0,
                    "excess_policy_currency": 150.0,
                    "excess_formatted": "A$ 150.00",
                    "excess_policy_currency_formatted": "A$ 150.00"
                }
            ],
            "commission": {
                "total_commission": 0.0,
                "total_commission_formatted": "A$ 0.00"
            },
            "created_at": "2020-02-06T00:12:30.974396Z",
            "confirmed_at": null,
            "updated_at": "2020-02-06T00:12:30.974411Z",
            "cancelled_at": null,
            "is_renewable": true,
            "cover_amount": 1349.0,
            "cover_amount_formatted": "A$ 1349.00",
            "pending_renewal": null,
            "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS?policy_type=product_insurance_v1",
            "discount_price": 124.85,
            "discount_price_formatted": "A$ 124.85",
            "discount_amount": 0.0,
            "discount_amount_formatted": "A$ 0.00"
        },
        "1": {
            "id": "063f9987-efae-4f29-8f85-9e6efa4299c1",
            "policy_start_date": "2020-02-06T13:00:00+00:00",
            "policy_end_date": "2021-02-06T13:00:00+00:00",
            "status": "RECEIVED",
            "price": 235.86,
            "price_formatted": "A$ 235.86",
            "policy": {
                "policy_type": "product_insurance",
                "policy_name": "Full Product Protection",
                "policy_code": "PFPO05CG",
                "policy_version": "7720b62b-3e84-446a-89d3-48c83cb39384",
                "category": "electronics-insurance",
                "content": {
                    "title": "Full Product Cover For Life",
                    "header": "Full Product Cover For Life",
                    "description": "Theft, damage and expanded warranty that covers the product for life. Cancel anytime.",
                    "optout_msg": "<p>.</p>",
                    "inclusions": [
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 235.86/year. Cancel anytime.",
                            "description": "Full replacement if the item can’t be repaired."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 235.86/year. Cancel anytime.",
                            "description": "Cancel anytime."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 235.86/year. Cancel anytime.",
                            "description": "Covers theft."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 235.86/year. Cancel anytime.",
                            "description": "Covers repairs when your item is damaged."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 235.86/year. Cancel anytime.",
                            "description": "Covers what the manufacturer's warranty doesn’t."
                        },
                        {
                            "title": "Get peace of mind with theft, damage and expanded warranty that covers the life of your product for only A$ 235.86/year. Cancel anytime.",
                            "description": "Extends warranty protection for the life of the policy."
                        }
                    ],
                    "disclaimer": "<p>I am over 18 and agree to the terms of this policy. This cover is powered by XCover.com and underwritten by Pacific International Insurance Pty Ltd.</p>"
                },
                "underwriter": {
                    "disclaimer": "This cover is powered by XCover and underwritten by Pacific International Insurance Pty. Ltd.",
                    "name": "Pacific International Insurance Pty. Ltd."
                }
            },
            "insured": null,
            "tax": {
                "total_tax": 40.93,
                "total_amount_without_tax": 194.93,
                "total_tax_formatted": "A$ 40.93",
                "total_amount_without_tax_formatted": "A$ 194.93",
                "taxes": [
                    {
                        "tax_amount": 21.44,
                        "tax_code": "SD",
                        "tax_amount_formatted": "A$ 21.44"
                    },
                    {
                        "tax_amount": 19.49,
                        "tax_code": "GST",
                        "tax_amount_formatted": "A$ 19.49"
                    },
                    {
                        "tax_amount": 0.0,
                        "tax_code": "ESL",
                        "tax_amount_formatted": "A$ 0.00"
                    }
                ]
            },
            "duration": "366 00:00:00",
            "benefits": [
                {
                    "description": "Damage or Theft",
                    "limit": 2549.87,
                    "limit_policy_currency": 2549.87,
                    "limit_formatted": "A$ 2549.87",
                    "limit_policy_currency_formatted": "A$ 2549.87",
                    "excess": 150.0,
                    "excess_policy_currency": 150.0,
                    "excess_formatted": "A$ 150.00",
                    "excess_policy_currency_formatted": "A$ 150.00"
                },
                {
                    "description": "Extended Warranty",
                    "limit": 2549.87,
                    "limit_policy_currency": 2549.87,
                    "limit_formatted": "A$ 2549.87",
                    "limit_policy_currency_formatted": "A$ 2549.87",
                    "excess": 150.0,
                    "excess_policy_currency": 150.0,
                    "excess_formatted": "A$ 150.00",
                    "excess_policy_currency_formatted": "A$ 150.00"
                }
            ],
            "commission": {
                "total_commission": 0.0,
                "total_commission_formatted": "A$ 0.00"
            },
            "created_at": "2020-02-06T00:12:31.008203Z",
            "confirmed_at": null,
            "updated_at": "2020-02-06T00:12:31.008217Z",
            "cancelled_at": null,
            "is_renewable": true,
            "cover_amount": 2549.0,
            "cover_amount_formatted": "A$ 2549.00",
            "pending_renewal": null,
            "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS?policy_type=product_insurance_v1",
            "discount_price": 235.86,
            "discount_price_formatted": "A$ 235.86",
            "discount_amount": 0.0,
            "discount_amount_formatted": "A$ 0.00"
        }
    },
    "bundle_code": null,
    "bundle_price": 360.71,
    "bundle_content": {},
    "bundle_price_formatted": "A$ 360.71",
    "bundle_discount_percent": 0.0,
    "bundle_discount_amount": 0.0,
    "bundle_discount_amount_formatted": "A$ 0.00"
}

{
    "currency": "AUD",
    "customer_country": "AU",
    "customer_language": "en",
    "partner_transaction_id": "1ef4472a-a50e-4c52-87e1-73b9ca988031",
    "request": [
        {
            "policy_type": "product_insurance",
            "policy_type_version": "2",
            "policy_start_date": "2021-01-14T18:30:00+00:00",
            "retail_value": 3799,
            "category": "Laptop",
            "title": "Apple MacBook Pro",
            "brand": "Apple",
            "model": "MacBook Pro",
            "description": "Apple Macbook Pro 16\" 2019 2.6 GHz w/ Touch Bar 512GB - Space Grey - Au Stock",
            "sku": "190199368477",
            "condition": "new"
        },
        {
            "policy_type": "product_insurance",
            "policy_type_version": "2",
            "policy_start_date": "2021-01-14T18:30:00+00:00",
            "retail_value": 3799,
            "category": "Mobile",
            "title": "Apple iPhone 12 Pro Max",
            "brand": "Apple",
            "model": "iPhone 12 Pro Max",
            "sku": "190199368478",
            "condition": "new"
        }
    ]
}

Retrieving Quote Information

When you request a quote, we send you back a quote package ID (INS number) in the response body, which can be used to retrieve information about all the quotes in the quote package. This is useful incase you don't want to store the Quote response on your side.

Retrieve a Quote

GET https://api.xcover.com/x/partners/:partner_id/quotes/:quote_package_id

The Quote Package ID is obtained during the Quote Request

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api-Key

string

API Key

{
    "id": "MPM49-EKX9D-INS",
    "status": "RECEIVED",
    "currency": "GBP",
    "total_price": 244.82,
    "total_price_formatted": "£244.82",
    "partner_transaction_id": "3ab19ca8-1b81-469f-ace5-33d3ccf29c83",
    "created_at": "2021-01-05T08:34:09.323201Z",
    "updated_at": "2021-01-05T08:34:09.323215Z",
    "pds_url": "https://www.xcover.com/en/pds/MPM49-EKX9D-INS",
    "security_token": "HthL6-gpJ5M-nu7sT-x7VkK",
    "quotes": {
        "0": {
            "id": "02ed6b9f-4a9a-4d48-a7e9-128cba071cec",
            "policy_start_date": "2021-01-14T18:30:00+00:00",
            "policy_end_date": "2022-01-13T18:30:00+00:00",
            "status": "RECEIVED",
            "price": 244.82,
            "price_formatted": "£244.82",
            "policy": {
                "policy_type": "product_insurance",
                "policy_name": "Full Product Protection OnBuy",
                "policy_code": "ONB01EL",
                "policy_version": "7a51eb83-dcc6-4639-bf97-ae1cde554416",
                "category": "electronics-insurance",
                "content": {
                    "title": "Full Product Protection",
                    "in_path_disclaimer": "You confirm you are over 18 and have read and agree to the <a href=\"https://www.xcover.com/en/pds/MPM49-EKX9D-INS?policy_type=product_insurance_v3\" target=\"_blank\">Policy Terms</a> & <a href=\"https://static.xcover.com/media/pds/7a51eb83-dcc6-4639-bf97-ae1cde554416/OnBuy_IPID_OkVuyYh.pdf\" target=\"_blank\">IPID</a>. The policy is provided by XCover.com (trading name of Cover Genius Ltd) and underwritten by Fortegra Europe Insurance Company Limited. Onbuy.com (Visor Commerce Ltd) is an Appointed Representative of Cover Genius Ltd who is authorised and regulated by the Financial Conduct Authority (FCA) reference 750711. This can be checked on the financial services register held on the FCA’s website (www.fca.org.uk). Fortegra Europe Insurance Company Limited is authorised and regulated by the MFSA."
                },
                "underwriter": {
                    "disclaimer": "This plan is arranged by XCover and underwritten by Fortegra Europe Insurance Company Limited.",
                    "name": "Fortegra Europe Insurance Company Limited"
                }
            },
            "insured": null,
            "tax": {
                "total_tax": 26.23,
                "total_amount_without_tax": 218.59,
                "total_tax_formatted": "£26.23",
                "total_amount_without_tax_formatted": "£218.59",
                "taxes": [
                    {
                        "tax_amount": 26.23,
                        "tax_code": "IPT",
                        "tax_amount_formatted": "£26.23"
                    }
                ]
            },
            "duration": "364 00:00:00",
            "benefits": [
                {
                    "description": "Accidental Damage",
                    "limit": 1623.51,
                    "limit_policy_currency": 1623.51,
                    "limit_formatted": "£1623.51",
                    "limit_policy_currency_formatted": "£1623.51",
                    "limit_per_unit": 541.17,
                    "limit_per_unit_policy_currency": 541.17,
                    "limit_per_unit_formatted": "£541.17 per item",
                    "limit_per_unit_policy_currency_formatted": "£541.17 per item",
                    "excess": 81.18,
                    "excess_policy_currency": 81.1755,
                    "excess_formatted": "£81.18",
                    "excess_policy_currency_formatted": "£81.18"
                },
                {
                    "description": "Theft",
                    "limit": 1623.51,
                    "limit_policy_currency": 1623.51,
                    "limit_formatted": "£1623.51",
                    "limit_policy_currency_formatted": "£1623.51",
                    "limit_per_unit": 541.17,
                    "limit_per_unit_policy_currency": 541.17,
                    "limit_per_unit_formatted": "£541.17 per item",
                    "limit_per_unit_policy_currency_formatted": "£541.17 per item",
                    "excess": 81.18,
                    "excess_policy_currency": 81.1755,
                    "excess_formatted": "£81.18",
                    "excess_policy_currency_formatted": "£81.18"
                },
                {
                    "description": "Mechanical Breakdown (when the manufacturer's warranty expires)",
                    "limit": 1623.51,
                    "limit_policy_currency": 1623.51,
                    "limit_formatted": "£1623.51",
                    "limit_policy_currency_formatted": "£1623.51",
                    "limit_per_unit": 541.17,
                    "limit_per_unit_policy_currency": 541.17,
                    "limit_per_unit_formatted": "£541.17 per item",
                    "limit_per_unit_policy_currency_formatted": "£541.17 per item",
                    "excess": 81.18,
                    "excess_policy_currency": 81.1755,
                    "excess_formatted": "£81.18",
                    "excess_policy_currency_formatted": "£81.18"
                }
            ],
            "commission": {
                "total_commission": 45.0,
                "total_commission_formatted": "£45.00"
            },
            "created_at": "2021-01-05T08:34:09.316598Z",
            "confirmed_at": null,
            "updated_at": "2021-01-05T08:34:09.316612Z",
            "cancelled_at": null,
            "is_renewable": false,
            "cover_amount": 541.0,
            "cover_amount_formatted": "£541.00 per item",
            "pds_url": "https://www.xcover.com/en/pds/MPM49-EKX9D-INS?policy_type=product_insurance_v3",
            "discount_price": 244.82,
            "discount_price_formatted": "£244.82",
            "discount_amount": 0.0,
            "discount_amount_formatted": "£0.00"
        }
    },
    "bundle_code": null,
    "bundle_price": 244.82,
    "bundle_content": {},
    "bundle_price_formatted": "£244.82",
    "bundle_discount_percent": 0.0,
    "bundle_discount_amount": 0.0,
    "bundle_discount_amount_formatted": "£0.00"
}

Update a Quote

Update Quote in Quote Package

PATCH https://api.xcover.com/x/partners/{partner_id}/quotes/{quote_package_id}/

Use this endpoint to mutate an existing Quote in a Quote Package.

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api_Key

string

API Key

{
  "id": "TLCC8-B6YWP-INS",
  "status": "RECEIVED",
  "currency": "USD",
  "total_price": 360.71,
  "total_price_formatted": "US$ 360.71",
  "partner_transaction_id": "ABCD-EFGG-0000-0000",
  "created_at": "2020-02-06T00:12:31.013656Z",
  "updated_at": "2020-02-06T00:12:31.013670Z",
  "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS",
  "quotes": {
    "0": {
      "id": "ca5c9839-17b3-4810-b0b1-d5b693ecef86",
      "policy_start_date": "2020-02-06T13:00:00+00:00",
      "policy_end_date": "2021-02-06T13:00:00+00:00",
      "status": "RECEIVED",
      "price": 124.85,
      "price_formatted": "US$ 124.85",
      "policy": {
        "policy_type": "product_insurance",
        "policy_name": "Full Product Protection",
        "policy_code": "PFPO05CG",
        "policy_version": "7720b62b-3e84-446a-89d3-48c83cb39384",
        "category": "electronics-insurance"
      },
      "insured": [
        {
          "first_name": "Bart",
          "last_name": "Simpson",
          "email": "[email protected]"
        }
      ]
    }
  },
  "bundle_code": null,
  "bundle_price": 360.71,
  "bundle_content": {},
  "bundle_price_formatted": "US$ 360.71",
  "bundle_discount_percent": 0.0,
  "bundle_discount_amount": 0.0,
  "bundle_discount_amount_formatted": "US$ 0.00"
}

{
    "currency": "USD",
    "request": [
        {
            "quote_id": "ca5c9839-17b3-4810-b0b1-d5b693ecef86",
            "insured": [
                {
                    "first_name": "Bart",
                    "last_name": "Simpson",
                    "email": "[email protected]"
                }
            ]
        }
    ]
}

Add Quote

Add Quote to Quote Package

POST https://api.xcover.com/x/partners/{partner_id}/quotes/{quote_package_id}/

The add endpoint can be used with an already generated INS (quote-package-id) to add new Quotes to an existing policy. For example: If the customer adds another Phone protection to their existing Product insurance policies, you could use this endpoint to add a new Quote to an existing Quote Package.

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api_Key

string

API Key

{
  "id": "TLCC8-B6YWP-INS",
  "status": "RECEIVED",
  "currency": "USD",
  "total_price": 360.71,
  "total_price_formatted": "US$ 360.71",
  "partner_transaction_id": "ABCD-EFGG-0000-0000",
  "created_at": "2020-02-06T00:12:31.013656Z",
  "updated_at": "2020-02-06T00:12:31.013670Z",
  "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS",
  "quotes": {
    "0": {
      "id": "ca5c9839-17b3-4810-b0b1-d5b693ecef86",
      "policy_start_date": "2020-02-06T13:00:00+00:00",
      "policy_end_date": "2021-02-06T13:00:00+00:00",
      "status": "RECEIVED",
      "price": 124.85,
      "price_formatted": "US$ 124.85",
      "policy": {
        "policy_type": "product_insurance",
        "policy_name": "Full Product Protection",
        "policy_code": "PFPO05CG",
        "policy_version": "7720b62b-3e84-446a-89d3-48c83cb39384",
        "category": "electronics-insurance"
      },
      "insured": [
        {
          "first_name": "Bart",
          "last_name": "Simpson",
          "email": "[email protected]"
        }
      ]
    }
  },
  "bundle_code": null,
  "bundle_price": 360.71,
  "bundle_content": {},
  "bundle_price_formatted": "US$ 360.71",
  "bundle_discount_percent": 0.0,
  "bundle_discount_amount": 0.0,
  "bundle_discount_amount_formatted": "US$ 0.00"
}

{
    "currency": "USD",
    "request": [
        {
            "policy_type": "product_insurance",
            "policy_type_version": "2",
            "policy_start_date": "2021-01-14T18:30:00+00:00",
            "retail_value": 450,
            "category": "Mobile",
            "title": "Samsung S8",
            "brand": "Samsung",
            "model": "S8",
            "sku": "1231231",
            "condition": "new"
        }
    ]
}

The add method can only be used for Quotes in the RECEIEVED status.

Remove Quote

Add Quote to Quote Package

POST https://api.xcover.com/x/partners/{partner_id}/quotes/{quote_package_id}/

The add endpoint can be used with an already generated INS (quote-package-id) to delete a specific policy, we need the ID of the Quote from the original request. Simply putting that id in the request will delete the right policy. For example: If the customer remove a product with protection from their cart.

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner Code

quote_package_id

string

Quote Package ID

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-Api_Key

string

API Key

{
  "id": "TLCC8-B6YWP-INS",
  "status": "RECEIVED",
  "currency": "USD",
  "total_price": 360.71,
  "total_price_formatted": "US$ 360.71",
  "partner_transaction_id": "ABCD-EFGG-0000-0000",
  "created_at": "2020-02-06T00:12:31.013656Z",
  "updated_at": "2020-02-06T00:12:31.013670Z",
  "pds_url": "https://staging.xcover.com/en/pds/TLCC8-B6YWP-INS",
  "quotes": {
    "0": {
      "id": "ca5c9839-17b3-4810-b0b1-d5b693ecef86",
      "policy_start_date": "2020-02-06T13:00:00+00:00",
      "policy_end_date": "2021-02-06T13:00:00+00:00",
      "status": "RECEIVED",
      "price": 124.85,
      "price_formatted": "US$ 124.85",
      "policy": {
        "policy_type": "product_insurance",
        "policy_name": "Full Product Protection",
        "policy_code": "PFPO05CG",
        "policy_version": "7720b62b-3e84-446a-89d3-48c83cb39384",
        "category": "electronics-insurance"
      },
      "insured": [
        {
          "first_name": "Bart",
          "last_name": "Simpson",
          "email": "[email protected]"
        }
      ]
    }
  },
  "bundle_code": null,
  "bundle_price": 360.71,
  "bundle_content": {},
  "bundle_price_formatted": "US$ 360.71",
  "bundle_discount_percent": 0.0,
  "bundle_discount_amount": 0.0,
  "bundle_discount_amount_formatted": "US$ 0.00"
}

{
    "quotes": [
        {
            "id": "ca5c9839-17b3-4810-b0b1-d5b693ecef86"
        }
    ]
}

The remove method can only be used for Quotes in the RECEIEVED status.

Instalments Workflow

This feature allows customers to pay for an insurance product that covers them for a period of time (annually) in instalments instead of up-front.

The above diagram illustrates the API calls and webhook events made in order to record the payment of each instalment.

Policy Instalment Options

When a quote request is made for a policy that allows payment to be made in instalments an instalment_plans property will be returned in the API response.

The amount to surface to the customer is reflected in the first_instalment_amount attribute.

{
    "quotes": {
        "0": {
            ...,
            "instalment_plans": [
                {
                    "name": "1year-monthly",
                    "label": "1Year-Monthly",
                    "amount": 308.0,
                    "first_instalment_amount": 25.67
                }
            ]
        }
    }
}

Confirming Instalment Plan

The instalment plan can be selected by provide the desired instalment name in the instalment_plan attribute during a booking request.

{
    "quotes": [
        {
            "id": "UUID",
            "instalment_plan": "1year-monthly"
        }
    ],
    "policyholder": {
        ...
    }
}

Processing a Periodic Payment

Depending on the payment services provider a periodic payment will generate a webhook event. This event should be processed by your platform and the following API calls should be made to the instalments endpoint.

Fetching Payment Plan Details

In order to record an instalment the correct instalment_id needs to be provided. The next scheduled instalment_id can be obtained by performing a GET request against the instalment endpoint.

Fetch Instalment Details

GET https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/instalments/

Returns instalment details including the payment schedule.

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner ID

quote_package_id

string

Quote Package ID (INS)

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-API-Key

string

API Key

{
    "quotes": [
        {
            "id": "95230b02-9f7f-463f-be6d-81b46e3c5955",
            "next_payment": {
                "id": "ba718007-964a-4115-b0f9-f746f20d6bdd",
                "number": 2,
                "quote": "95230b02-9f7f-463f-be6d-81b46e3c5955",
                "period_start_date": "2021-09-25T02:47:00Z",
                "period_end_date": "2021-10-24T02:47:00Z",
                "status": "UNPAID",
                ..
                "tax": {
                    "taxes": [],
                    "total_amount_without_tax": "7.50",
                    "total_amount_without_tax_formatted": "€7.50"
                },
                "surcharges": {},
                "payment_failures": null
            },
            "paid_until": "2021-08-25T02:47:12.115862Z",
            "payment_schedule": [
                {
                    "id": "2b0c7a96-be7a-450b-86b1-04feb5813b37",
                    "number": 1,
                   ....
                },
            "total_amount_paid": 7.5,
            "total_amount_due": 82.5
        }
    ],
    "currency": "USD"
}

Confirming an Instalment Transaction

To confirm the instalment once a payment attempt has been made a request to the following endpoint needs to be made containing the instalment_id from the previous step.

Confirm Instalment

POST https://api.xcover.com/x/partners/:partner_id/bookings/:quote_package_id/instalments/

Confirms the instalment providing whether the payment was successful or not.

Path Parameters

Name

Type

Description

partner_id

string

Unique Partner ID

quote_package_id

string

Quote Package ID (INS)

Headers

Name

Type

Description

Content-Type

string

application/json

Date

string

Current Datetime

Authorization

string

HMAC Signature

X-API-Key

string

API Key

{
    // Response
}

{
  "quotes": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "instalment_id": "286b1dc2-e2f0-40ea-bc39-079ef019b7d0",
      "instalment_number": 0,
      "payment_attempted_date": "2019-08-24T14:15:22Z",
      "payment_status": "PAID",
      "payment_failures": {}
    }
  ]
}