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.

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.

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.

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

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

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

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:

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

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

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

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

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

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

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