• Choose the right workflow based on nature of business

  • Events / Tickets

  • Travel / Accommodation

  • Parcel / Shipping

  • Product / Retail

• Obtain Sandbox access credentials from Cover Genius CSE (Client Solutions Engineer)

• Implement the Purchase Workflow

• Implement the Cancellation Workflow

• Implement the Modification Workflow

• Test using Sandbox credentials

• Obtain Test Production credentials from CSE

• Deploy integration to Pre Production environment

• Share Pre Production access details with CSE

• CSE performs end-to-end testing in Pre Production and Cover Genius Compliance Manager signs off on integration

• Fix any issues that arise

• Final testing and sign-off carried out by CSE

• Obtain Production credentials from CSE

• Production deployment date scheduled with CSE

• Deploy integration to Production environment

• Start selling insurance policies

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: and . 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. 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

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

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

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.

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.

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.

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 Dual Payment method 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 Dual Payment method. 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:

  "partner_metadata": {
        "trip_name": "Holiday trip",
        "primary_contact": "Dana Skulky",
        "primary_contact_number": "+123123123",
        "primary_contact_email": "[email protected]",
        "custom_platform_transaction_reference": "XZY123" }

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.

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.

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 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 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.

A XCover Quote Package and individual Quotes within a Quote Package can transition between several different statuses. The below is a state diagram of these transitions and their conditions.

Claims Handling

Due to their regulated nature, claims are solely handled by Cover Genius. Cover Genius is responsible for all communications with users, claims assessment and claims payments. Users can lodge the claim on by completing an online, pre-filled form, provide a description of the situation/event and provide any supporting information or documents required. Generally, in situations where customers contact your platform in regards to claims, they should be redirected to .

First Notice of Loss (FNOL)

Users will need to submit a first notice of loss form (FNOL) in order for claims to be assessed. Generally, this is completed by a logged in user at .

Claim Assessment

Claims will be assessed by Cover Genius via our in-house claims assessment system. We leverage our technology and existing policy data to provide efficient and automated approval process, and fast electronic claims payment.

Medical and Emergency Claims

Medical assistance and medical-related claims may be handled by our underwriting partners directly. Cover Genius works with our underwriters to create a user-centric workflow to ensure a smooth process relevant to your use case.

Can we integrate claims submission ourselves?

Generally, claims are solely managed by Cover Genius. If you wish to discuss integrating claims submission into your experience, please contact your partnership manager.

XCover uses conventional HTTP response codes to indicate the success or failure of API requests. Error codes ranging from 200 to 299 indicate successful operations. Error codes ranging from 400 to 499 represent various error codes. Errors that can be resolved programmatically will result in an error code that briefly explains the error type and the reason for failure. 5xx codes indicate an unexpected error within the XCover application. In the unlikely event of a 5xx error, our engineering team will automatically receive a notification and will fix the issue as fast as possible.

After booking and over the course of using a policy, users may need to manage their policy, to view and reference their policy inclusions, limits, or terms and conditions, and to update their account information. In most instances, this is performed on XCover.com Partners may wish to include a link to this page in their experience, and often a specific policy URL will be appropriate to include, such as: Claims: https://xcover.com/en/account/claims/fnol?bookingID=1ABCD-VWXYZ-INS Modification: https://xcover.com/en/modify/1ABCD-VWXYZ-INS Certificate of Insurance (COI): https://xcover.com/en/coi/1ABCD-VWXYZ-INS Policy Disclosure Statement / Policy Wording (PDS): https://xcover.com/en/pds/1ABCD-VWXYZ-INS Users will also need to have created an account before using these links. In most cases, users will receive an account creation email containing a specific login URL shared with them after booking, usually via a policy confirmation email.

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.

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.

1. A simple script is used as a wrapper for the quote request

2. If custom display settings are required, they may be applied using signals or taken from quote request variables (see below example).

3. Using Content Delivery Network (CDN), offers are displayed within the purchase flow on partner site.

4. 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

Error Handling

XCover uses conventional HTTP response codes to indicate the success or failure of an API request. Error codes ranging from 400 to 499 represent various error codes. Errors that can be resolved programmatically will result in an error code that briefly explains the type of error or reason for the error. In the unlikely event of a 5xx error, our engineering team will automatically receive a report and will fix any issue as fast as possible.

Note the below workflow for error handling:

XCover strongly recommends the following mechanisms for error handling:

Retry Mechanism

The request/response goes through various hops between Partners and XCover. These may include various networks and servers. If at any point, the request fails due to network issue for example (e.g. a timeout), Partners should try to resend the request at least twice to rule out any intermittent issue. For Asynchronous request situations, retries may be spaced comfortably, ideally 2-5 mins apart before sending out an alert for someone to manually check any issues. We recommend at least 5 second timeout for bookings, and setting it to 10 seconds or more should be more reliable and not be a problem for customers. If requests fail, they should be retried with exponential backoff. In case the booking creation failed 5 times, partners should flag and raise with Cover Genius. Similar logic should apply for cancellations.

Alert Mechanism

If, after the second try Partners fail to receive the expected response (received, confirmed etc), it is recommended to establish alert mechanisms that notify responsible teams of the failure.

Logging Mechanism

Irrespective of a correct or a failed request/response, it is highly recommended for Partners to log requests and responses all centrally. These assist investigation where besides direct issue itself, patterns may become visible, helping to identify overarching issues.

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.

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

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):

1. Price

2. Disclaimer

3. Policy wording link

4. 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

3. Policy Wording, taken from the "pds_url" quote response field, for example: "view wording" as a hyperlink of: "ABCD-1234-INS"

Generally, the quote display should address:

1. Customer relevance - Does the quote/product presentation make sense for this purchase flow?

2. Compliance and regulatory requirements - Does the offer meet requirements for disclaimers, price, statements of fact, and availability of policy wording?

3. Marketing copy and trust - Is the offer likely to be understood and selected by the customer? Is the offer trusted/compelling?

An XCover Quote Package and individual Quotes within a Quote Package can transition between several different statuses. Below is a state diagram of these transitions and their conditions.

The XCover API operates with a set number of states that a quote can rest in. RECEIVED: Refers to an initial quote creation state - this is not a live policy, but may be booked from this state. CONFIRMED: A booked policy, this policy is confirmed as being paid for and activated. It may be active or expired. May be cancellable or modifiable, and can be claimed against. CANCELLED: A cancelled policy cannot be claimed against, or modified. DELETED: A rare status that depicts a removed quote/booking. PENDING_PAYMENT: Only relevant for quotes that are booked using the require_payment_confirmation flag during a create booking request (usually followed by the confirm booking request) end state if confirmed will be CONFIRMED. FAILED: A failed quote status. RENEWED: A state used to depict a renewed prior booked policy (for example after an annual renewal payment is confirmed).

Common FAQs by Insurance Vertical

Travel / Accommodation

Property / Renters

Parcel / Shipping

Product / Retail

General API FAQs

Due to the regulated nature of insurance customers must receive email communication about their coverage from the licensed entity distributing the insurance.

Usually, customers will receive these emails from our brands rentalcover.com, xcover.com and sweetly.com with no issues. The advent of new and convenient sign-up/in methods such as "Sign in with Apple" allows users to use an anonymous email address. When a user provides such an address to your app or website, the private relay email service routes all emails between you and the user. A private relay email service sends email to a recipient using an automatically generated email address. This hides the real email address to preserve privacy.

By default, this prevents third parties such as Cover Genius and its associated brands from sending emails to customers who opt into this service which presents a compliance issue for Cover Genius and you as a distribution partner.

Thankfully Apple provides a simple process for adding third-party domains. If you currently allow customers to "Sign in with Apple" or are planning to in the future please follow these steps to ensure customers receive emails from Cover Genius and its associated brands:

1. In Certificates, Identifiers & Profiles, click More in the sidebar, then click Configure under Sign in with Apple for Email Communication.

2. In the Email Sources section, click the add button (+) on the top left.

3. Copy the following comma-delimited list: xcover.com,rentalcover.com,go.xcover.com,covergenius.com

4. Paste the comma-delimited list of Cover Genius domains that will be used for email communication, then click Next.

5. Confirm your entered email sources and click Register.

6. The table will display if the registered email source domain passed an SPF check.

All SPF checks should pass, if there is an issue please get in touch with your assigned CSE (Client Solutions Engineer) or Partner Growth Manager.

Customers will now be able to receive email communication from Cover Genius and its associated brands.

API Errors

(Stated in headers): In API Guide, global environment based Basic approach: “Does the API respond with a 20X response?” Useful for: - General API function - Confirmation of actions - Basic operation validation

Example of use: - Was a quote request received? - Was a booking request received? - Was there any full failures

Logic Errors

Logic errors are present in API response body, are case by case, and policy based. They are often the indicator of a problem with the booking or quote, and may represent a partial booking failure. Always look for the "errors" array. Basic approach: “Does the request contain any content concerns, or logical failures?” Useful for: - Calculation issues - Confirmation over various state actions (does a booking match a quote expectation) - In depth rule validation Example of use: - Was a quote request valid? - Was a booking request complete, were there any partial failures?

Logic error management:

1. All quotes in a quote or booking request should be confirmed individually (not just package, or package status). An erroneous quote will return a "null" response for the object. Example:
2. Booking request items should be confirmed similarly Example, basic elements present, first quote id sent also present

3. Booking request shouldn't have errors, mismatched values, or null quote responses

In the below example, the booking was successful, but partially failed due to a component quote having a logic error.

1. A null quote component will result in a differing value for the policy bundle, even in a confirmed state.

Understanding and monitoring for these response variations and errors will greatly reduce misalinged bookings and improve customer satisfaction.

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:

1. Prepare request data for signing.

2. Sign data using one of the HMAC algorithms such as SHA1 (dprecated), SHA256 , SHA384 or SHA512 algorithms.

3. Encode the signature using Base64 encoding.

4. URL encode the result of the previous step.

5. Prepare Authorization header containing the Base64 and URL encoded signature string, API Key and the algorithm used, for example hmac-sha512.

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.

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

Query Parameters

Headers

{
  "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"
        }
    ]
}

For certain policy types (eg. Warranty/Product Insurance/Renters) a renewal period may be established for ongoing protection. Eg. A laptop warranty with an annual renewal cycle. Or a renters insurance product

Before the policy end date the customer should be sent a notification that their policy is expiring and will be (auto) renewed (depending on their settings in your platform).

An example of the renewal workflow is illustrated below.

Quote for Renewal

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

Generates an updated booking with a renewal price that should be charged to the customer. It also contains any other changes to benefits/limits or policy wording that may have changed since the first policy was purchased. Request contains no payload.

Path Parameters

Headers

Confirm Renewal

To confirm a renewal once payment has been collected a request to the following endpoint needs to be made.

Confirm Renewal

POST https://api.xcover.com/x/partners/:partner_id/renewals/:quote_package_id/confirm/:renewal_id/

Confirms the renewal and issues the updated policy to the customer.

Path Parameters

Headers

Request Body

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

Headers

{
    "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

Headers

{
    // 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": {}
    }
  ]
}

The API adheres to the REST principles and provides developers-friendly, predictive and logically organised resource-oriented structure.

Dates

XCover API accepts date and date-time parameters in the format as defined by RFC 3339, section 5.6, for example 2018-01-01, 2018-01-01T17:00:01Z, 2018-01-01T17:00:00+01:00, 2018-01-01T17:00:01.04399-04:00. We encourage partners to keep the original timezone in contrast to sending all dates in UTC. Having original timezone can helps XCover to deal with potential issues with DST changes.

Country Codes

All country codes provided in API requests must be compliant with ISO 3166-1 Alpha-2 standard.

Currency

Currency must be compliant with 3-letter codes as defined by ISO 4217.

Languages

Language input must be compliant with 2-letter codes as defined but ISO 639-1 standard. Variations of base languages use a variant indicator, for example: "en-us" to specify english, united states variant (where applicable).

Telephone (Mobile Phone) numbers

Phone numbers provided (at booking stage) should predominantly be of personal mobile/cell type, with the format of +[country_code] plus a phone number, e.g., +61412345678 In some use cases, XCover will validate the phone number format (to allow sending SMS policy and claim communications to the customer), and return an error if an invalid format is provided.

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

{
  "id": "string",
  "status": "string",
  "currency": "str",
  "total_price": 0,
  "total_price_formatted": "string",
  "partner_transaction_id": "string",
  "created_at": "2021-01-04T17:10:37Z",
  "updated_at": "2021-01-04T17:10:37Z",
  "pds_url": "http://example.com",
  "security_token": "string",
  "quotes": [
    {
      "id": "string",
      "policy_start_date": "2021-01-04T17:10:37Z",
      "policy_end_date": "2021-01-04T17:10:37Z",
      "status": "string",
      "price": 0,
      "price_formatted": "string",
      "policy": {
        "policy_type": "string",
        "policy_name": "string",
        "policy_code": "string",
        "policy_version": "string",
        "category": "string",
        "content": {
          "title": "string",
          "header": "string",
          "description": "string",
          "optout_msg": "string",
          "inclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "exclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "disclaimer": "string",
          "disclaimer_html": "string",
          "payment_disclaimer": "string",
          "in_path_disclaimer": "string"
        },
        "underwriter": {
          "disclaimer": "string",
          "name": "string"
        }
      },
      "insured": [
        {
          "id": "string",
          "first_name": "string",
          "middle_name": "string",
          "last_name": "string",
          "email": "[email protected]",
          "country": "AF",
          "address1": "string",
          "address2": "string",
          "city": "string",
          "postcode": "string",
          "region": "string",
          "phone": "string",
          "age": 0,
          "birth_date": "2021-01-04",
          "metadata": {
            "property1": "string",
            "property2": "string"
          },
          "company": "string"
        }
      ],
      "tax": {
        "total_tax": 0,
        "total_amount_without_tax": 0,
        "total_tax_formatted": "string",
        "total_amount_without_tax_formatted": "string",
        "taxes": [
          {
            "tax_amount": 0,
            "tax_code": "string",
            "tax_amount_formatted": "string"
          }
        ]
      },
      "duration": "string",
      "benefits": [
        {
          "description": "string",
          "limit_description": "string",
          "limit": 0,
          "limit_policy_currency": 0,
          "limit_formatted": "string",
          "limit_policy_currency_formatted": "string",
          "limit_per_unit": 0,
          "limit_per_unit_policy_currency": 0,
          "limit_per_unit_formatted": "string",
          "limit_per_unit_policy_currency_formatted": "string",
          "excess_description": "string",
          "excess": 0,
          "excess_policy_currency": 0,
          "excess_formatted": "string",
          "excess_policy_currency_formatted": "string",
          "minimum_claim_amount": 0,
          "minimum_claim_amount_policy_currency": 0,
          "minimum_claim_amount_formatted": "string",
          "minimum_claim_amount_policy_currency_formatted": "string"
        }
      ],
      "commission": {
        "total_commission": 0,
        "total_commission_formatted": "string"
      },
      "created_at": "2021-01-04T17:10:37Z",
      "confirmed_at": "2021-01-04T17:10:37Z",
      "updated_at": "2021-01-04T17:10:37Z",
      "cancelled_at": "2021-01-04T17:10:37Z",
      "is_renewable": true,
      "cover_amount": 0,
      "cover_amount_formatted": "string",
      "pds_url": "http://example.com",
      "attachments": "string",
      "files": "string",
      "extra_fields": {
        "property1": "string",
        "property2": "string"
      },
      "next_renewal": {
        "id": "string",
        "package_id": "string",
        "quote_id": "string",
        "status": "string",
        "start_date": "2021-01-04T17:10:37Z",
        "notification_date": "2021-01-04T17:10:37Z",
        "due_date": "2021-01-04T17:10:37Z",
        "expiry_date": "2021-01-04T17:10:37Z",
        "cancelled_on": "2021-01-04T17:10:37Z",
        "paid_on": "2021-01-04T17:10:37Z",
        "created_at": "2021-01-04T17:10:37Z"
      },
      "can_be_cancelled": true,
      "errors": [
        "string"
      ]
    }
  ],
  "coi": {
    "pdf": "http://example.com",
    "url": "http://example.com"
  },
  "account_url": "http://example.com",
  "policyholder": {
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "email": "[email protected]",
    "phone": "string",
    "country": "AF",
    "age": 0,
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postcode": "string",
    "region": "string",
    "secondary_email": "[email protected]",
    "birth_date": "2021-01-04",
    "company": "string",
    "tax_payer_id": "string"
  },
  "total_tax": 0,
  "total_tax_formatted": "string",
  "total_premium": 0,
  "total_premium_formatted": "string"
}

{
    "quotes": [
        {
            "id": "d7780bcc-c47c-446b-a9fb-b41f62fc1e81",
            "insured": [
                {
                    "first_name": "User",
                    "last_name": "Example",
                    "birth_date": "1991-03-11",
                    "email": "[email protected]"
                }
            ]
        }
    ],
    "policyholder": {
        "first_name": "User",
        "last_name": "Example",
        "birth_date": "1991-03-11",
        "email": "[email protected]",
        "country": "GB"
    }
}

 "id": "ABCD-12345-INS",
    "status": "CONFIRMED",
    "currency": "AUD",
    "total_price": 100.0,

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.

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

{
  "id": "string",
  "status": "string",
  "currency": "str",
  "total_price": 0,
  "total_price_formatted": "string",
  "partner_transaction_id": "string",
  "created_at": "2021-01-04T17:10:37Z",
  "updated_at": "2021-01-04T17:10:37Z",
  "pds_url": "http://example.com",
  "security_token": "string",
  "quotes": [
    {
      "id": "string",
      "policy_start_date": "2021-01-04T17:10:37Z",
      "policy_end_date": "2021-01-04T17:10:37Z",
      "status": "string",
      "price": 0,
      "price_formatted": "string",
      "policy": {
        "policy_type": "string",
        "policy_name": "string",
        "policy_code": "string",
        "policy_version": "string",
        "category": "string",
        "content": {
          "title": "string",
          "header": "string",
          "description": "string",
          "optout_msg": "string",
          "inclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "exclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "disclaimer": "string",
          "disclaimer_html": "string",
          "payment_disclaimer": "string",
          "in_path_disclaimer": "string"
        },
        "underwriter": {
          "disclaimer": "string",
          "name": "string"
        }
      },
      "insured": [
        {
          "id": "string",
          "first_name": "string",
          "middle_name": "string",
          "last_name": "string",
          "email": "[email protected]",
          "country": "AF",
          "address1": "string",
          "address2": "string",
          "city": "string",
          "postcode": "string",
          "region": "string",
          "phone": "string",
          "age": 0,
          "birth_date": "2021-01-04",
          "metadata": {
            "property1": "string",
            "property2": "string"
          },
          "company": "string"
        }
      ],
      "tax": {
        "total_tax": 0,
        "total_amount_without_tax": 0,
        "total_tax_formatted": "string",
        "total_amount_without_tax_formatted": "string",
        "taxes": [
          {
            "tax_amount": 0,
            "tax_code": "string",
            "tax_amount_formatted": "string"
          }
        ]
      },
      "duration": "string",
      "benefits": [
        {
          "description": "string",
          "limit_description": "string",
          "limit": 0,
          "limit_policy_currency": 0,
          "limit_formatted": "string",
          "limit_policy_currency_formatted": "string",
          "limit_per_unit": 0,
          "limit_per_unit_policy_currency": 0,
          "limit_per_unit_formatted": "string",
          "limit_per_unit_policy_currency_formatted": "string",
          "excess_description": "string",
          "excess": 0,
          "excess_policy_currency": 0,
          "excess_formatted": "string",
          "excess_policy_currency_formatted": "string",
          "minimum_claim_amount": 0,
          "minimum_claim_amount_policy_currency": 0,
          "minimum_claim_amount_formatted": "string",
          "minimum_claim_amount_policy_currency_formatted": "string"
        }
      ],
      "commission": {
        "total_commission": 0,
        "total_commission_formatted": "string"
      },
      "created_at": "2021-01-04T17:10:37Z",
      "confirmed_at": "2021-01-04T17:10:37Z",
      "updated_at": "2021-01-04T17:10:37Z",
      "cancelled_at": "2021-01-04T17:10:37Z",
      "is_renewable": true,
      "cover_amount": 0,
      "cover_amount_formatted": "string",
      "pds_url": "http://example.com",
      "attachments": "string",
      "files": "string",
      "extra_fields": {
        "property1": "string",
        "property2": "string"
      },
      "next_renewal": {
        "id": "string",
        "package_id": "string",
        "quote_id": "string",
        "status": "string",
        "start_date": "2021-01-04T17:10:37Z",
        "notification_date": "2021-01-04T17:10:37Z",
        "due_date": "2021-01-04T17:10:37Z",
        "expiry_date": "2021-01-04T17:10:37Z",
        "cancelled_on": "2021-01-04T17:10:37Z",
        "paid_on": "2021-01-04T17:10:37Z",
        "created_at": "2021-01-04T17:10:37Z"
      },
      "can_be_cancelled": true,
      "errors": [
        "string"
      ]
    }
  ],
  "coi": {
    "pdf": "http://example.com",
    "url": "http://example.com"
  },
  "account_url": "http://example.com",
  "policyholder": {
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "email": "[email protected]",
    "phone": "string",
    "country": "AF",
    "age": 0,
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postcode": "string",
    "region": "string",
    "secondary_email": "[email protected]",
    "birth_date": "2021-01-04",
    "company": "string",
    "tax_payer_id": "string"
  },
  "total_tax": 0,
  "total_tax_formatted": "string",
  "total_premium": 0,
  "total_premium_formatted": "string"
}

{
    "currency": "USD",
    "customer_language": "en",
    "request": [
        {
            "policy_type": "parcel_insurance",
            "policy_type_version": "1",
            "policy_start_date": "2021-03-07T09:25:00+00:00",
            "shipping_cost": 0.0,
            "order_total": 0.0,
            "shipping_date": "2021-03-07T09:25:00+00:00",
            "carrier": "Fedex",
            "carrier_service_name": "Fedex",
            "declared_value": 4000.0,
            "delivery_confirmation_type": "None",
            "delivery_confirmation_price": 0,
            "partner_price": 30.0,
            "sender": {
                "first_name": "Homer",
                "last_name": "Simpson",
                "company_name": "The Simpsons LLC",
                "address1": "742 Evergreen Terrace",
                "city": "Springfield",
                "postcode": "98122",
                "region": "WA",
                "country": "US",
                "email": "[email protected]"
            },
            "receiver": {
                "first_name": "Charles Montgomery",
                "last_name": "Burns",
                "company_name": "Springfield Nuclear Power Plant",
                "address1": "100 Industrial Way",
                "city": "Sprinfield",
                "postcode": "98122",
                "region": "WA",
                "country": "US",
                "email": "[email protected]"
            },
            "tracking_reference": "SNDR5152",
            "tracking_url": "http://www.tracking-example-url.com/tracking/SNDR5152",
            "packages": [
                {
                    "declared_value": 4000.0,
                    "description": "Test",
                    "type": "Package",
                    "width": 2.0,
                    "height": 2.0,
                    "length": 2.0,
                    "weight": 1.0,
                    "items": [],
                    "tracking_reference": "SNDR5152",
                    "tracking_url": "http://www.tracking-example-url.com/tracking/SNDR5152"
                }
            ]
        }
    ],
    "policyholder": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "address1": "742 Evergreen Terrace",
        "city": "Springfield",
        "postcode": "98122",
        "region": "WA",
        "country": "US",
        "email": "[email protected]"
    }
}

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

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

Webhooks allow partners to be notified when important events happen in XCover. When one of those events are triggered, we will send an HTTP POST payload to the webhook's configured URL. Webhooks can be used to send a customer notification, initiate a policy renewal process or perform any custom logic. To establish webhooks, partners can provide to their CSE: 1. Listener URL 2. Authentication Key & Secret 3. Support URL 4. Requested events (CSE may propose or suggest these as part of solutioning).

We will provide an HTTP signature generated on our end in Authorization header and the api key itself in X-Api-Key header. We will base the signature on your provided key pair. You can use the same HMAC based algorithm for signature verification, if required. Please use the information from the signature header to check which hash algorithm is used in order to validate the request. Currently, webhook requests are signed using sha256 algorithm.

In case of multiple failures with the webhook notification, where the partner supplied endpoint does not respond with a 200 OK, we will try the webhook for up to 3 times.

Authentication

Your webhook API endpoint should implement HMAC authentication to verify that the API request was sent and signed by XCover.

import base64
import hashlib
import hmac
from urllib.parse import unquote

# You will provide your assigned Client Solution Engineer with an API key and secret
# they will configure the XCover platform
api_key = "--your-api-key--"
secret = "--your-secret--"
# This is just an example, you would obtain this from your server library
# E.g. a Flask server
# from flask import Flask, request
# app = Flask(__name__)
# @app.post('/my-xcover-webhook')
# def xcover_webhook():
#.   request_headers = request.headers 
#    return do_everything_below()

request_headers = {
    'X-Api-Key': '--api-key--',
    'Authorization': '--signature--',
    'Date': 'Thu, 27 Feb 2025 05:01:47 GMT'
}

# Extract signature from the request headers
auth_header = request_headers.get('Authorization', '')
if not auth_header.startswith('Signature '):
    raise ValueError("Invalid Authorization header")

auth_parts = dict(
    part.split('=', 1) for part in 
    auth_header.replace('Signature ', '').split(',')
)
received_signature = unquote(auth_parts.get('signature', '').strip('"'))

# Compute the expected signature
date_header = request_headers.get('Date')
if not date_header:
    raise ValueError("Missing Date header")

raw = f"date: {date_header}"

expected_hash = hmac.new(
    secret.encode("utf-8"),
    raw.encode("utf-8"),
    hashlib.sha256
).digest()

expected_signature = base64.b64encode(expected_hash).decode('utf-8')

is_valid = hmac.compare_digest(expected_signature, received_signature)

BOOKING_CREATED

Description: The payload is sent in a webhook to the Partner whenever the Booking is Created through an API Request.

{
  'event': 'BOOKING_CREATED',
  'payload': {
    'id': '8AMKH-KQ8NR-INS',
    'status': 'CONFIRMED',
    'currency': 'USD',
    'total_price': 68.71,
    'total_price_formatted': 'US$68.71',
    'partner_transaction_id': null,
    'quotes': [
      {
        'id': '8bfb48ab-6947-4f34-a932-c4dcede958f6',
        'policy_start_date': '2023-10-08T00:00:49.751227+00:00',
        'policy_end_date': '2023-10-13T00:00:49.751247+00:00',
        'status': 'CONFIRMED',
        'price': 68.71,
        'price_formatted': 'US$68.71',
        'policy': {
          'policy_type': 'travel_medical',
          'policy_name': 'PolicyVersion 0',
          'policy_version': 'e94df011-ee0b-44a1-bdb1-1dd05cb67fc7'
        },
        'duration': '5 00:00:00.000020',
        'total_renewed_times': 0
      }
    ]
  }
}

BOOKING_UPDATED

Description: The payload is sent to the Partner whenever the Booking is Updated through an API Request

{
  'event': 'BOOKING_UPDATED',
  'payload': {
    'id': 'TKBZN-XGPAX-INS',
    'status': 'CONFIRMED',
    'currency': 'USD',
    'total_price': 68.71,
    'total_price_formatted': 'US$68.71',
    'partner_transaction_id': null,
    'quotes': [
      {
        'id': '4d3b7919-9372-4c54-bdaf-05f770ffc2fc',
        'policy_start_date': '2023-10-08T01:09:19.649112+00:00',
        'policy_end_date': '2023-10-13T01:09:19.649133+00:00',
        'status': 'CONFIRMED',
        'price': 68.71,
        'price_formatted': 'US$68.71',
        'policy': {
          'policy_type': 'travel_medical',
          'policy_name': 'PolicyVersion 0',
          'policy_version': '1637bc92-0299-4624-8f38-c9b9e15d379e'
        },
        'duration': '5 00:00:00.000021',
        'total_renewed_times': 0
      }
    ]
  }
}  

BOOKING_CANCELLED

Description: The payload is sent to the Partner whenever the Booking is cancelled through an API Request

{
  'event': 'BOOKING_CANCELLED',
  'payload': {
    'id': 'HMZZ8-3YYHZ-INS',
    'status': 'CANCELLED',
    'currency': 'USD',
    'total_price': 0.0,
    'total_price_formatted': 'US$0.00',
    'partner_transaction_id': null,
    'quotes': [
      {
        'id': 'e0925616-824d-4216-bd18-450fb669c017',
        'policy_start_date': '2023-10-08T01:19:41.766661+00:00',
        'policy_end_date': '2023-10-13T01:19:41.766719+00:00',
        'status': 'CANCELLED',
        'price': 68.71,
        'price_formatted': 'US$68.71',
        'policy': {
          'policy_type': 'travel_medical',
          'policy_name': 'PolicyVersion 0',
          'policy_version': 'dd5aef78-5ce5-4f19-a455-968780b89ea2'
        },
        'duration': '5 00:00:00.000058',
        'total_renewed_times': 0,
        'refund_value': 68.71
      }
    ]
  }
}

RENEWAL_CREATED

Description: Used to notify partner that the policy has been renewed.

Example:

{
    "event": "RENEWAL_CREATED",
    "payload": {
        "id": "daSJp-fwdoj-REN",
        "package_id": "GKDK9-CECQU-INS",
        "quote_id": "c8ddb161-e3d9-455b-9621-96df90f17acb",
        "status": "ACTIVE",
        "start_date": "2019-02-25T13:00:00Z",
        "notification_date": "2018-11-22T00:21:41Z",
        "due_date": "2019-02-25T13:00:00Z",
        "expiry_date": "2018-11-21T22:56:01Z",
        "cancelled_on": null,
        "paid_on": "2019-02-25T13:00:00Z",
        "created_at": "2018-11-21T04:15:12.175468Z"
    }
}

RENEWAL_NOTIFICATION

Description: Used to notify partner about approaching renewal.

Example:

{
    "event": "RENEWAL_NOTIFICATION",
    "payload": {
        "id": "daSJp-fwdoj-REN",
        "package_id": "GKDK9-CECQU-INS",
        "quote_id": "c8ddb161-e3d9-455b-9621-96df90f17acb",
        "status": "ACTIVE",
        "start_date": "2019-02-25T13:00:00Z",
        "notification_date": "2018-11-22T00:21:41Z",
        "due_date": "2019-02-25T13:00:00Z",
        "expiry_date": "2018-11-21T22:56:01Z",
        "cancelled_on": null,
        "paid_on": null,
        "created_at": "2018-11-21T04:15:12.175468Z"
    }
}

RENEWAL_DUE

Description: Sent on the renewal due date, the customer policy will be active until the end of the grace period (expiry_date).

Example:

{
    "event": "RENEWAL_DUE",
    "payload": {
        "id": "daSJp-fwdoj-REN",
        "package_id": "GKDK9-CECQU-INS",
        "quote_id": "c8ddb161-e3d9-455b-9621-96df90f17acb",
        "status": "DUE",
        "start_date": "2019-02-25T13:00:00Z",
        "notification_date": "2018-11-22T00:21:41Z",
        "due_date": "2019-02-25T13:00:00Z",
        "expiry_date": "2018-11-21T22:56:01Z",
        "cancelled_on": null,
        "paid_on": null,
        "created_at": "2018-11-21T04:15:12.175468Z"
    }
}

RENEWAL_EXPIRED

Description: Sent on the renewal expiry date, the customer policy is no longer renewable after this event is triggered.

Example:

{
    "event": "RENEWAL_DUE",
    "payload": {
        "id": "daSJp-fwdoj-REN",
        "package_id": "GKDK9-CECQU-INS",
        "quote_id": "c8ddb161-e3d9-455b-9621-96df90f17acb",
        "status": "DUE",
        "start_date": "2019-02-25T13:00:00Z",
        "notification_date": "2018-11-22T00:21:41Z",
        "due_date": "2019-02-25T13:00:00Z",
        "expiry_date": "2018-11-21T22:56:01Z",
        "cancelled_on": null,
        "paid_on": null,
        "created_at": "2018-11-21T04:15:12.175468Z"
    }
}

XCover enables the world’s largest ecommerce companies to protect all of their customers.

The XCover platform includes an easy-to-use API integration to promote, sell, and manage insurance products provided by Cover Genius underwriting partners. It is designed to seamlessly integrate with any ecommerce platform and sell any line of insurance products.

This is made possible by the XCover API, a flexible interface based on that returns standard HTTP response codes and -encoded responses.

Please, for the latest updates.

Integration outline

This outline is intended to provide an overview of the integration workflows for anyone working with an XCover API integration, including (but not limited to): Product & Project Managers, Software Engineers, and Business Analysts.

It demonstrates an example XCover distribution partner with a typical online store.

Quote

The store uses XCover API to quote for insurance prices for the product insurance policies and offers to their customer to purchase ancillary insurance products along with the main products. Customers can add the insurance product to their shopping cart and continue to checkout. Alternatively, they can opt-out from the insurance offering and proceed to checkout with the main product only.

Booking

After successful checkout, the store calls XCover API to notify about the policies purchased and provides the policyholder information. XCover API will inform customers about all the insurance product features, offer to create an account on to the XCover.com website where they can modify, renew, cancel the purchased policies, or lodge a claim. XCover takes care of registering the purchased policies with the underwriting partners as well.

Modifications

If booking Modifications are allowed by the underwriting partner XCover allows booking modification by customers via XCover.com. Alternatively, booking modifications can be triggered by one of the partner's platforms via XCover API.

Cancellation

It can happen that the customer is not happy with the product purchased and wants to return it. XCover API offers cancellation workflows that allow the previously issued policy to be canceled and refunded automatically in this case.

Renewals

XCover.com also offers automatic renewals when it is required by the integration.

Claims

Customers can always send a claim via XCover.com in case if one of the conditions under the policy is triggered. XCover offers highly automated and fast quote assessments and payouts via its XClaim and XPay internal APIs.

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

{
    "id": "8WD8Y-LTEKE-INS",
    "status": "CONFIRMED",
    "currency": "USD",
    "total_price": 4.27,
    "total_price_formatted": "US$4.27",
    "partner_transaction_id": "id-to-stitch-transactions-in-two-systems",
    "created_at": "2021-01-15T01:19:49.529799Z",
    "updated_at": "2021-01-15T01:19:59.773302Z",
    "pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS",
    "security_token": "UiRlP-6bLfQ-1YLjR-ste66",
    "quotes": [
        {
            "id": "201eb11b-4494-40e8-97fa-e107c76501bf",
            "policy_start_date": "2021-01-17T13:00:00+00:00",
            "policy_end_date": "2021-01-19T13:00:00+00:00",
            "status": "CONFIRMED",
            "price": 4.27,
            "price_formatted": "US$4.27",
            "policy": {
                "policy_type": "event_ticket_protection",
                "policy_name": "Missed Event Cover (Generic)",
                "policy_code": "MECG0001",
                "policy_version": "5d24e2d1-a341-4b8b-9917-82878470a9c3",
                "category": "event_ticket_protection",
                "content": {
                    "title": "Missed Event Cover for Justin Bibber",
                    "header": null,
                    "description": "90% of attendees add Missed Event Cover for generous protection when things go wrong or your plans change. For only  per ticket it covers you - and all ticket holders - if:",
                    "optout_msg": "",
                    "disclaimer": "<p>This insurance is arranged by Cover Genius Ltd which is authorised and regulated by the FCA (No.750711). Policies are underwritten by Markel International Insurance Company Limited which is authorised by the PRA and regulated by the FCA, (No.202570).</p>"
                },
                "underwriter": {
                    "disclaimer": "This plan is arranged by XCover.com",
                    "name": "Cover Genius Pty Ltd"
                },
                "claim_selector_id": null
            },
            "insured": [
                {
                    "id": "3aa30165-7a71-45ab-8899-f479fcb6e8e2",
                    "first_name": "Darin",
                    "last_name": "Sikanic",
                    "email": "[email protected]",
                    "region": null
                }
            ],
            "tax": {
                "total_tax": 0.0,
                "total_amount_without_tax": 4.27,
                "total_tax_formatted": "US$0.00",
                "total_amount_without_tax_formatted": "US$4.27",
                "taxes": []
            },
            "duration": "2 00:00:00",
            "benefits": [
                {
                    "description": "Updated Transalation",
                    "limit": 7.77,
                    "limit_policy_currency": 10.0,
                    "limit_formatted": "US$7.77",
                    "limit_policy_currency_formatted": "A$10.00",
                    "excess": 3.88,
                    "excess_policy_currency": 5.0,
                    "excess_formatted": "US$3.88",
                    "excess_policy_currency_formatted": "A$5.00"
                },
                {
                    "description": "Updated Transalation",
                    "limit_description": "Benefit Text Test 01",
                    "excess": 4.66,
                    "excess_policy_currency": 6.0,
                    "excess_formatted": "US$4.66",
                    "excess_policy_currency_formatted": "A$6.00"
                },
                {
                    "description": "Description",
                    "limit": 11.65,
                    "limit_policy_currency": 15.0,
                    "limit_formatted": "US$11.65",
                    "limit_policy_currency_formatted": "A$15.00"
                },
                {
                    "description": "Description",
                    "limit": 15.54,
                    "limit_policy_currency": 20.0,
                    "limit_formatted": "US$15.54",
                    "limit_policy_currency_formatted": "A$20.00",
                    "excess_description": "Excess Text Test 01"
                },
                {
                    "description": "Description",
                    "limit_description": "Benefit Text Test 02",
                    "excess_description": "Excess Text Test 02"
                }
            ],
            "commission": {
                "total_commission": 0.0,
                "total_commission_formatted": "US$0.00"
            },
            "created_at": "2021-01-15T01:19:49.523137Z",
            "confirmed_at": "2021-01-15T01:19:59.750719Z",
            "updated_at": "2021-01-15T01:19:59.763517Z",
            "cancelled_at": null,
            "is_renewable": false,
            "cover_amount": 77.7,
            "cover_amount_formatted": "US$77.70",
            "pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS?policy_type=event_ticket_protection_v1",
            "attachments": [],
            "files": [],
            "extra_fields": {},
            "next_renewal": null,
            "can_be_cancelled": true
        }
    ],
    "coi": {
        "url": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS?security_token=UiRlP-6bLfQ-1YLjR-ste66",
        "pdf": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS.pdf?security_token=UiRlP-6bLfQ-1YLjR-ste66"
    },
    "account_url": "https://staging.xcover.com/en/account?id=0bde2670-c3f9-4e79-a837-063d5d5e3874&signup_token=zl4qR-wNoL5-fHZ4M-u0Lmb",
    "policyholder": {
        "first_name": "Ben",
        "middle_name": null,
        "last_name": "H",
        "email": "[email protected]",
        "phone": null,
        "country": "US",
        "age": null,
        "address1": null,
        "address2": null,
        "city": null,
        "postcode": null,
        "region": "NYC",
        "secondary_email": null,
        "birth_date": null,
        "company": null
    },
    "total_tax": 0.0,
    "total_tax_formatted": "US$0.00",
    "total_premium": 4.27,
    "total_premium_formatted": "US$4.27",
    "partner": {
        "id": "87ZRF",
        "name": "Generic Partner",
        "title": "Generic Partner",
        "logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
        "contact_url": "https://staging.xcover.com/en/about",
        "partner_url": "https://staging.xcover.com",
        "help_center_url": "https://staging.xcover.com/en/help/your-insurance",
        "updated_at": "2020-10-28T07:48:24.671777Z",
        "xpay_refund_enabled": false,
        "subsidiary": {
            "id": "87ZRF",
            "name": "Generic Partner",
            "title": "Generic Partner",
            "logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
            "contact_url": "https://staging.xcover.com/en/about",
            "partner_url": "https://staging.xcover.com",
            "help_center_url": "https://staging.xcover.com/en/help/your-insurance",
            "updated_at": "2020-10-28T07:48:24.671777Z",
            "xpay_refund_enabled": false
        }
    },
    "customer_language": "en"
}

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.

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

{
  "id": "string",
  "status": "string",
  "quotes": [
    {
      "id": "string",
      "policy_start_date": "2020-09-25T05:31:10Z",
      "policy_end_date": "2020-09-25T05:31:10Z",
      "policy_cancellation_date": "2020-09-25T05:31:10Z",
      "policy_coolingoff_date": "2020-09-25T05:31:10Z",
      "status": "string",
      "price": 0,
      "refund_value": 0,
      "adjustment_fee": 0,
      "policy": {
        "policy_type": "string",
        "policy_name": "string",
        "policy_code": "string",
        "policy_version": "string",
        "category": "string",
        "content": {
          "title": "string",
          "header": "string",
          "description": "string",
          "optout_msg": "string",
          "inclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "exclusions": [
            {
              "title": "string",
              "description": "string"
            }
          ],
          "disclaimer": "string",
          "disclaimer_html": "string"
        },
        "underwriter": {
          "disclaimer": "string",
          "name": "string"
        }
      },
      "insured": [
        {
          "id": "string",
          "first_name": "string",
          "middle_name": "string",
          "last_name": "string",
          "email": "[email protected]",
          "country": "AF",
          "address1": "string",
          "address2": "string",
          "city": "string",
          "postcode": "string",
          "region": "string",
          "phone": "string",
          "age": 0,
          "birth_date": "2020-09-25",
          "metadata": {
            "property1": "string",
            "property2": "string"
          },
          "company": "string"
        }
      ],
      "created_at": "2020-09-25T05:31:10Z",
      "confirmed_at": "2020-09-25T05:31:10Z",
      "updated_at": "2020-09-25T05:31:10Z",
      "cancelled_at": "2020-09-25T05:31:10Z"
    }
  ],
  "policyholder": {
    "first_name": "string",
    "middle_name": "string",
    "last_name": "string",
    "email": "[email protected]",
    "phone": "string",
    "country": "AF",
    "age": 0,
    "address1": "string",
    "address2": "string",
    "city": "string",
    "postcode": "string",
    "region": "string",
    "secondary_email": "[email protected]",
    "birth_date": "2020-09-25",
    "company": "string",
    "tax_payer_id": "string"
  },
  "pds_url": "http://example.com",
  "coi": {
    "pdf": "http://example.com",
    "url": "http://example.com"
  },
  "created_at": "2020-09-25T05:31:10Z",
  "updated_at": "2020-09-25T05:31:10Z",
  "total_price": 0,
  "total_price_formatted": "string",
  "total_refund": 0,
  "total_refund_formatted": "string",
  "total_tax": 0,
  "total_tax_formatted": "string",
  "total_premium": 0,
  "total_premium_formatted": "string",
  "currency": "str",
  "cancellation_id": "string",
  "confirm_before": "2020-09-25T05:31:10Z",
  "partner": {
    "id": "string",
    "name": "string",
    "title": "string",
    "logo": "http://example.com",
    "contact_url": "http://example.com",
    "partner_url": "http://example.com",
    "help_center_url": "http://example.com",
    "updated_at": "2020-09-25T05:31:10Z",
    "xpay_refund_enabled": true,
    "subsidiary": {
      "id": "string",
      "name": "string",
      "title": "string",
      "logo": "http://example.com",
      "contact_url": "http://example.com",
      "partner_url": "http://example.com",
      "help_center_url": "http://example.com"
    }
  }
}

{
    "quotes": [
        {
            "id": "62fd1f8b-f8fa-420a-82a0-6990976fb8cc",
            "reason_for_cancellation": "No longer travelling"
        }
    ]
}

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.

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

{
  "id": "8UHPK-ALPQT-INS",
  "status": "CANCELLED",
  "quotes": [
    {
      "id": "d5465e90-f22f-477a-b0cc-2950fcf034ff",
      "policy_start_date": "2021-01-07T18:18:48Z",
      "policy_end_date": "2021-01-17T15:45:00Z",
      "policy_cancellation_date": null,
      "policy_coolingoff_date": "2021-01-21T18:18:59.940059Z",
      "status": "CANCELLED",
      "price": 22.4,
      "refund_value": 22.4,
      "adjustment_fee": 0.0,
      "created_at": "2021-01-07T18:18:49.035218Z",
      "confirmed_at": "2021-01-07T18:18:59.940059Z",
      "updated_at": "2021-01-07T18:19:04.222570Z",
      "cancelled_at": null
    }
  ],
  "created_at": "2021-01-07T18:18:49.145872Z",
  "updated_at": "2021-01-07T18:18:59.958252Z",
  "total_price": 0.0,
  "total_price_formatted": "€0.00",
  "total_refund": 22.4,
  "total_refund_formatted": "22.40",
  "currency": "EUR",
  "cancellation_id": "90o3N-fIexx-Zw2bd-CCL",
  "confirm_before": "2021-01-08T18:19:04.228699Z"
}

{
    "preview": true,
    "quotes": [
        {
            "id": "62fd1f8b-f8fa-420a-82a0-6990976fb8cc",
            "reason_for_cancellation": "No longer travelling"
        }
    ]
}

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

{
  "id": "8UHPK-ALPQT-INS",
  "status": "CANCELLED",
  "quotes": [
    {
      "id": "d5465e90-f22f-477a-b0cc-2950fcf034ff",
      "policy_start_date": "2021-01-07T18:18:48Z",
      "policy_end_date": "2021-01-17T15:45:00Z",
      "policy_cancellation_date": null,
      "policy_coolingoff_date": "2021-01-21T18:18:59.940059Z",
      "status": "CANCELLED",
      "price": 22.4,
      "refund_value": 22.4,
      "adjustment_fee": 0.0,
      "created_at": "2021-01-07T18:18:49.035218Z",
      "confirmed_at": "2021-01-07T18:18:59.940059Z",
      "updated_at": "2021-01-07T18:19:04.222570Z",
      "cancelled_at": null
    }
  ],
  "created_at": "2021-01-07T18:18:49.145872Z",
  "updated_at": "2021-01-07T18:18:59.958252Z",
  "total_price": 0.0,
  "total_price_formatted": "€0.00",
  "total_refund": 22.4,
  "total_refund_formatted": "22.40",
  "currency": "EUR",
  "cancellation_id": "90o3N-fIexx-Zw2bd-CCL",
  "confirm_before": "2021-01-08T18:19:04.228699Z"
}

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

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

{
    "id": "8WD8Y-LTEKE-INS",
    "status": "CONFIRMED",
    "currency": "USD",
    "total_price": 4.27,
    "total_price_formatted": "US$4.27",
    "partner_transaction_id": "id-to-stitch-transactions-in-two-systems",
    "created_at": "2021-01-15T01:19:49.529799Z",
    "updated_at": "2021-01-15T01:19:59.773302Z",
    "pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS",
    "security_token": "UiRlP-6bLfQ-1YLjR-ste66",
    "quotes": [
        {
            "id": "201eb11b-4494-40e8-97fa-e107c76501bf",
            "policy_start_date": "2021-01-17T13:00:00+00:00",
            "policy_end_date": "2021-01-19T13:00:00+00:00",
            "status": "CONFIRMED",
            "price": 4.27,
            "price_formatted": "US$4.27",
            "policy": {
                "policy_type": "event_ticket_protection",
                "policy_name": "Missed Event Cover (Generic)",
                "policy_code": "MECG0001",
                "policy_version": "5d24e2d1-a341-4b8b-9917-82878470a9c3",
                "category": "event_ticket_protection",
                "content": {
                    "title": "Missed Event Cover for Justin Bibber",
                    "header": null,
                    "description": "90% of attendees add Missed Event Cover for generous protection when things go wrong or your plans change. For only  per ticket it covers you - and all ticket holders - if:",
                    "optout_msg": "",
                    "disclaimer": "<p>This insurance is arranged by Cover Genius Ltd which is authorised and regulated by the FCA (No.750711). Policies are underwritten by Markel International Insurance Company Limited which is authorised by the PRA and regulated by the FCA, (No.202570).</p>"
                },
                "underwriter": {
                    "disclaimer": "This plan is arranged by XCover.com",
                    "name": "Cover Genius Pty Ltd"
                },
                "claim_selector_id": null
            },
            "insured": [
                {
                    "id": "3aa30165-7a71-45ab-8899-f479fcb6e8e2",
                    "first_name": "Darin",
                    "last_name": "Sikanic",
                    "email": "[email protected]",
                    "region": null
                }
            ],
            "tax": {
                "total_tax": 0.0,
                "total_amount_without_tax": 4.27,
                "total_tax_formatted": "US$0.00",
                "total_amount_without_tax_formatted": "US$4.27",
                "taxes": []
            },
            "duration": "2 00:00:00",
            "benefits": [
                {
                    "description": "Updated Transalation",
                    "limit": 7.77,
                    "limit_policy_currency": 10.0,
                    "limit_formatted": "US$7.77",
                    "limit_policy_currency_formatted": "A$10.00",
                    "excess": 3.88,
                    "excess_policy_currency": 5.0,
                    "excess_formatted": "US$3.88",
                    "excess_policy_currency_formatted": "A$5.00"
                },
                {
                    "description": "Updated Transalation",
                    "limit_description": "Benefit Text Test 01",
                    "excess": 4.66,
                    "excess_policy_currency": 6.0,
                    "excess_formatted": "US$4.66",
                    "excess_policy_currency_formatted": "A$6.00"
                },
                {
                    "description": "Description",
                    "limit": 11.65,
                    "limit_policy_currency": 15.0,
                    "limit_formatted": "US$11.65",
                    "limit_policy_currency_formatted": "A$15.00"
                },
                {
                    "description": "Description",
                    "limit": 15.54,
                    "limit_policy_currency": 20.0,
                    "limit_formatted": "US$15.54",
                    "limit_policy_currency_formatted": "A$20.00",
                    "excess_description": "Excess Text Test 01"
                },
                {
                    "description": "Description",
                    "limit_description": "Benefit Text Test 02",
                    "excess_description": "Excess Text Test 02"
                }
            ],
            "commission": {
                "total_commission": 0.0,
                "total_commission_formatted": "US$0.00"
            },
            "created_at": "2021-01-15T01:19:49.523137Z",
            "confirmed_at": "2021-01-15T01:19:59.750719Z",
            "updated_at": "2021-01-15T01:19:59.763517Z",
            "cancelled_at": null,
            "is_renewable": false,
            "cover_amount": 77.7,
            "cover_amount_formatted": "US$77.70",
            "pds_url": "https://staging.xcover.com/en/pds/8WD8Y-LTEKE-INS?policy_type=event_ticket_protection_v1",
            "attachments": [],
            "files": [],
            "extra_fields": {},
            "next_renewal": null,
            "can_be_cancelled": true
        }
    ],
    "coi": {
        "url": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS?security_token=UiRlP-6bLfQ-1YLjR-ste66",
        "pdf": "https://staging.xcover.com/en/coi/8WD8Y-LTEKE-INS.pdf?security_token=UiRlP-6bLfQ-1YLjR-ste66"
    },
    "account_url": "https://staging.xcover.com/en/account?id=0bde2670-c3f9-4e79-a837-063d5d5e3874&signup_token=zl4qR-wNoL5-fHZ4M-u0Lmb",
    "policyholder": {
        "first_name": "Ben",
        "middle_name": null,
        "last_name": "H",
        "email": "[email protected]",
        "phone": null,
        "country": "US",
        "age": null,
        "address1": null,
        "address2": null,
        "city": null,
        "postcode": null,
        "region": "NYC",
        "secondary_email": null,
        "birth_date": null,
        "company": null
    },
    "total_tax": 0.0,
    "total_tax_formatted": "US$0.00",
    "total_premium": 4.27,
    "total_premium_formatted": "US$4.27",
    "partner": {
        "id": "87ZRF",
        "name": "Generic Partner",
        "title": "Generic Partner",
        "logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
        "contact_url": "https://staging.xcover.com/en/about",
        "partner_url": "https://staging.xcover.com",
        "help_center_url": "https://staging.xcover.com/en/help/your-insurance",
        "updated_at": "2020-10-28T07:48:24.671777Z",
        "xpay_refund_enabled": false,
        "subsidiary": {
            "id": "87ZRF",
            "name": "Generic Partner",
            "title": "Generic Partner",
            "logo": "https://staging.static.xcover.com/media/partnerlogos/2020/08/12/travel_logo.png",
            "contact_url": "https://staging.xcover.com/en/about",
            "partner_url": "https://staging.xcover.com",
            "help_center_url": "https://staging.xcover.com/en/help/your-insurance",
            "updated_at": "2020-10-28T07:48:24.671777Z",
            "xpay_refund_enabled": false
        }
    },
    "customer_language": "en"
}