XCover API (v2 – 2.87.0)

Download OpenAPI specification:Download

Welcome to XCover - Enabling the World's Largest eCommerce Companies to Sell Insurance

XCover is the platform that delivers on our vision to sell insurance on the World's largest sites. Please follow us on Linkedin for API updates. The following policy types are available in XCover's API:

  • Travel: Accommodation Cancelation
  • Services: Assistance Services
  • Commercial: BOP Insurance
  • Commercial: Business Insurance
  • Mobility: On-Site Caravan Protection
  • Ecommerce: clyde_product_insurance
  • Travel Zero: Comprehensive Travel Insurance
  • Travel: Comprehensive Travel Insurance Covid Cancellation Component
  • Travel: Comprehensive Travel Insurance Ground
  • Travel: Comprehensive Travel Insurance Version 6
  • Logistics: Container Protection
  • Logistics: Container Protection (Recipient Test)
  • Property: Contents Insurance for Landlords
  • Property: Corporate Property Protection
  • Cyber: Cyber Insurance
  • Retail: Device Protection
  • Gig Economy: Driver Protection
  • Earthquake: Earthquake Cover
  • Retail: Ecomm Insurance (inc. Electronics, Jewellery, Musical Instruments, Sports Outdoor Equipment and Sunglasses)
  • Event: Missed Event Cover (Easol)
  • Event: Missed Event Cover
  • Gig Economy: Flight Delay (Generic)
  • Property: Full Property Protection
  • Commercial: GL Insurance
  • Health: Health Cover
  • Property: Home Warranty
  • Property: Home Warranty Cover
  • Stays: Hotel Experience
  • Stays: Hotel Trips Cover
  • Property: Landlord Liability Insurance
  • Logistics: Parcel Insurance
  • Health: Pet Insurance
  • Retail: Product Insurance (inc. Electronics, Jewellery, Musical Instruments, Sports Outdoor Equipment and Sunglasses)
  • Retail: Product Insurance (inc. Electronics, Jewellery, Musical Instruments, Sports Outdoor Equipment and Sunglasses)
  • Commercial: Product Liability Insurance
  • Retail: Product warranty
  • Property: Property Protection
  • Travel: Quarantine Cover
  • Travel: Rental Cover Policies
  • Rental Cars: Rental Cars
  • Property: Rental Property Protection
  • Renters: Renters Insurance
  • Gig Economy: Rider Insurance
  • Stays: Stay Comprehensive
  • Guarantee: Tracker warranty
  • Travel: Travel Coach Protection
  • Travel: Emergency Medical & Expenses (C)
  • Travel: Trip Cancellation
  • Travel Standalone: Trip Cancellation
  • Travel: Trip Cancellation (Unbundled)
  • Travel: Flight Delay
  • Travel: Personal Items, Electronics & Baggage Cover
  • Travel: Insolvency Protection Insurance
  • Travel Standalone: Insolvency Protection Insurance
  • Travel: Insolvency Protection Insurance
  • Travel Zero: Emergency Medical & Expenses
  • Travel Standalone: Emergency Medical & Expenses (Standalone)
  • Travel: Emergency Medical & Expenses
  • Travel: Personal Baggage
  • Travel: Personal Electronics
  • Travel: travel_ticket_cover
  • Travel: Trip Cancellation
  • Other APIs:

    • RentalCover.com – our API for car rental agents.
    • BrightWrite – price and product optimisation API.
    • XClaim (api documentation is coming soon).

    Introduction

    This document describes the API resources available to promote XCover insurance products on your own website.

    The XCover API adheres to the principles of a REST architectural style. It is user-friendly: it is predictive, with logically organized resource-oriented URLs, and it uses HTTP response codes to indicate any errors (explained under the Error section).

    We will offer a sandbox environment that you can use to test the XCover API and its integration. The sandbox environment can be used with testing-only API keys.

    We encourage you to subscribe to XCover's API mailing list to receive the latest updates and features.

    Authentication

    All HTTP requests sent to the XCover API must be signed with a special signature to be fully authenticated, and must also be provided in the 'Authorization' header of the HTTP request. To do this, you can obtain an API key and a secret signing key from your account manager. Please note that a new signature will be generated for each request.

    To generate a signature:

    1. Prepare your request information for signing
    2. Sign data using one of the HMAC algorithms such as SHA1 (deprecated), SHA256 , SHA384 or SHA512 algorithms. Please note that the date string to be signed should be in RFC 822 Section 5.1 format e.g. Thu, 04 Nov 2021 18:07:11 GMT The date must be padded e.g. 04
    3. Encode the resulting string (the signature) in Base64 and do URL encoding of the result.
    4. Put the API key, URL encoded signature, and the algorithm used in the Authorization header

    The code below provides an example of a signature generation. You can also use the code below 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
    

    Note: Requests are automatically signed if you are using one of XCover's API SDKs. Ask your integration manager for an SDK version for your language. At the moment we support Python and PHP, but a new version of SDK could be released on demand.

    You can receive an API key, API secret, and Partner ID from your integration manager.

    Error Codes

    XCover uses conventional HTTP response codes to indicate the success or failure of an API request. Error codes ranging from 200 to 299 indicate a successful operation. 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. 5xx codes indicate an error within the XCover servers, which will be minimized on our end. In the unlikely event of a 5xx error, our engineering team will automatically receive a report and will fix the issue as fast as possible.

    Status Description
    200 - OK Everything worked as expected.
    201 - Created The request has been fulfilled and has resulted in one or more new resources being created.
    400 - Bad Request The request was not accepted, often due to the wrong format of the request.
    401 - Unauthorized No valid API key was provided.
    402 - Request Failed The parameters were valid, but the request failed.
    404 - Not Found The requested resource doesn't exist.
    409 - Conflict The request conflicts with another request, perhaps due to the usage of the same idempotency key.
    422 - Unprocessable Entity Used mostly for validation or logical errors.
    429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential back-off of your requests.
    500, 502, 503, 504 - Server Errors Something went wrong on XCovers's end. (These are rare, we promise!)

    Data Formats

    Dates

    The XCover API accepts date and date-time parameters in the format as defined by: RFC 3339, section 5.6, e.g. 2018-01-01, 2018-01-01T17:00:01Z, 2018-01-01T17:00:00+01:00, 2018-01-01T17:00:01.04399-04:00. Even though you can technically always send the XCover API dates in the UTC timezone format, we encourage you to keep the original timezone format, so as to avoid potential issues (such as DST changes).

    Country Codes

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

    Currency

    All currency fields must be compliant with 3-letter codes as defined by ISO 4217.

    Webhooks

    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. If a webhook call fails, it will be automatically retried for at most 3 times.

    We will provide an HTTP signature generated on our end in Authorization header and the api key itself in X-Api-Key header. 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.

    The available webhooks are listed below:

    BOOKING_CREATED

    Description: Sent when a Booking is created through an API Request

    Example:

    {
      '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: Sent whenever the Booking is Updated through an API Request

    Example:

    {
      '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: Sent whene the Booking is cancelled through an API Request

    Example:

    {
      '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 still be renewable 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 sent.

    Example:

    {
        "event": "RENEWAL_EXPIRED",
        "payload": {
            "id": "daSJp-fwdoj-REN",
            "package_id": "GKDK9-CECQU-INS",
            "quote_id": "c8ddb161-e3d9-455b-9621-96df90f17acb",
            "status": "UNPAID",
            "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"
        }
    }