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:
Other APIs:
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:
Authorization headerThe 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.testing_api_key,
apiSecret = environment.testing_api_secret,
date = (new Date()).toUTCString(),
signatureContentString = 'date: ' + date,
signatureString = CryptoJS.HmacSHA256(signatureContentString, apiSecret).toString(CryptoJS.enc.Base64),
authHeader = 'Signature keyId="' + apiKey + '",algorithm="hmac-sha256",signature="' + encodeURIComponent(signatureString) + '"';
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.
| 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!) |
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.
In case of multiple failures with the webhook notification, where the partner supplied endpoint does not respond with a 200 OK, we send out a notification to the support URL for the partner with information about the failing endpoint.
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.
The available webhooks and their response examples are listed below:
Description: The payload is sent in a webhook to the Partner whenever the Booking is Created through an API Request
Example:
{
"event": "BOOKING_CREATED",
"payload": {
"id": "1412e83c-fed7-4e64-b441-68a36cee057d",
"policy_start_date": "2021-01-18T02:43:28.352000+00:00",
"policy_end_date": "2021-05-03T02:43:28.353000+00:00",
"status": "CONFIRMED",
"price": 5.33,
"price_formatted": "€5.33",
"policy": {
"policy_type": "travel_flight_cancellation_cover",
"policy_name": "Trip Cancellation",
"policy_code": "TCAN09TL",
"policy_version": "5d606484-e029-4603-936b-0a3320ff8917",
"category": null,
"content": {
"title": "Trip Cancellation Title",
"header": "Cover for Air & Travel Costs",
"description": "If you need to cancel for medical reasons - we've got you covered. Covers prepaid travel expenses (air, hotels, cars, tours) if you need to cancel - before or after departure - due to illness to yourself or your travel group. You're also covered if your family gets sick. Claims are paid instantly.",
"optout_msg": "",
"inclusions": [
{
"title": "If you, your travel companion or close relative is injured or ill (pre or post departure)",
"description": "You're covered for your prepaid travel costs"
}
],
"exclusions": [
{
"title": "You're not covered if...",
"description": "Your cancellation claim results from pre-existing medical conditions"
}
],
"disclaimer": "This plan is arranged by XCover.com, a trading name of Cover Genius Ltd. and underwritten by Isosceles PCC Limited.",
"disclaimer_html": "<p>This plan is arranged by XCover.com, a trading name of Cover Genius Ltd. and underwritten by Isosceles PCC Limited.</p>",
"payment_disclaimer": "",
"in_path_disclaimer": ""
},
"underwriter": {
"disclaimer": "This plan was arranged by XCover.com",
"name": "Cover Genius Singapore Pte. Ltd"
},
"claim_selector_id": "test_claim_id_123",
"pds_name": "travel_flight_cancellation_cover_v3",
"previous_policy_id": "0aa82c5d-f97a-4a4e-803f-db09f909f3b3",
"pds_version": "1.0",
"content_version": "1.0",
"pricing_expression_version": null
},
"insured": [
{
"id": "6fce9904-dd0d-44ae-b63b-c0efe034716d",
"first_name": "John",
"last_name": "Adams",
"email": "[email protected]",
"region": null,
"age": 32,
"birth_date": "1987-02-24"
}
],
"tax": {
"total_tax": 0.15,
"total_amount_without_tax": 5.18,
"total_tax_formatted": "€0.15",
"total_amount_without_tax_formatted": "€5.18",
"taxes": [
{
"tax_amount": 0.15,
"tax_code": "Tax & Surcharge (label)",
"tax_amount_formatted": "€0.15"
}
]
},
"duration": "105 00:00:00.001000",
"benefits": [
{
"description": "Full Reimbursement of Program Fee",
"limit": 50,
"limit_policy_currency": 50,
"limit_formatted": "€50.00",
"limit_policy_currency_formatted": "€50.00",
"limit_per_unit": 20,
"limit_per_unit_policy_currency": 20,
"limit_per_unit_formatted": "€20.00 ",
"limit_per_unit_policy_currency_formatted": "€20.00 ",
"excess": 100,
"excess_policy_currency": 100,
"excess_formatted": "€100.00",
"excess_policy_currency_formatted": "€100.00",
"minimum_claim_amount": 15,
"minimum_claim_amount_policy_currency": 15,
"minimum_claim_amount_formatted": "€15.00",
"minimum_claim_amount_policy_currency_formatted": "€15.00"
}
],
"commission": {
"total_commission": 0,
"total_commission_formatted": "€0.00"
},
"created_at": "2021-01-13T02:43:29.370220Z",
"confirmed_at": "2021-01-13T02:53:40.339274Z",
"updated_at": "2021-01-13T02:53:40.354372Z",
"cancelled_at": null,
"is_renewable": true,
"cover_amount": null,
"cover_amount_formatted": null,
"pds_url": "https://staging.xcover.com/en/pds/QYCTR-8GGTN-INS?policy_type=travel_flight_cancellation_cover_v1",
"attachments": [],
"files": [],
"extra_fields": {},
"discount_price": 5.33,
"discount_price_formatted": "€5.33",
"discount_amount": 0,
"discount_amount_formatted": "€0.00",
"package": {
"id": "QYCTR-8GGTN-INS",
"status": "CONFIRMED",
"currency": "EUR",
"total_price": 5.33,
"total_price_formatted": "€5.33",
"partner_transaction_id": "ABCD-EFGH-1234-5789",
"created_at": "2021-01-13T02:43:29.378873Z",
"updated_at": "2021-01-13T02:53:40.364112Z",
"pds_url": "https://staging.xcover.com/en/pds/QYCTR-8GGTN-INS",
"bundle_code": null,
"bundle_price": 5.33,
"bundle_content": {},
"bundle_price_formatted": "€5.33",
"bundle_discount_percent": 0,
"bundle_discount_amount": 0,
"bundle_discount_amount_formatted": "€0.00",
"customer": {
"id": "26d6eef1-30a2-4ed0-9c35-633a9a22dac7",
"first_name": "John",
"last_name": "Adams",
"age": null,
"email": "[email protected]",
"country": "AU",
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": null,
"phone": null,
"secondary_email": null,
"birth_date": null,
"company": null
},
"customer_region": null,
"customer_postcode": null,
"customer_country": "PH",
"policyholder": {
"first_name": "John",
"middle_name": null,
"last_name": "Adams",
"email": "[email protected]",
"phone": null,
"country": "AU",
"age": null,
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": null,
"secondary_email": null,
"birth_date": null,
"company": null,
"tax_payer_id": null
}
}
}
}Description: The payload is sent to the Partner whenever the Booking is Updated through an API Request
Example:
{
"event": "BOOKING_UPDATED",
"payload": {
"id": "1412e83c-fed7-4e64-b441-68a36cee057d",
"policy_start_date": "2021-01-18T02:43:28.352000+00:00",
"policy_end_date": "2021-05-03T02:43:28.353000+00:00",
"status": "CONFIRMED",
"price": 5.33,
"price_formatted": "€5.33",
"policy": {
"policy_type": "travel_flight_cancellation_cover",
"policy_name": "Trip Cancellation",
"policy_code": "TCAN09TL",
"policy_version": "5d606484-e029-4603-936b-0a3320ff8917",
"category": null,
"content": {
"title": "Trip Cancellation Title",
"header": "Cover for Air & Travel Costs",
"description": "If you need to cancel for medical reasons - we've got you covered. Covers prepaid travel expenses (air, hotels, cars, tours) if you need to cancel - before or after departure - due to illness to yourself or your travel group. You're also covered if your family gets sick. Claims are paid instantly.",
"optout_msg": "",
"inclusions": [
{
"title": "If you, your travel companion or close relative is injured or ill (pre or post departure)",
"description": "You're covered for your prepaid travel costs"
}
],
"exclusions": [
{
"title": "You're not covered if...",
"description": "Your cancellation claim results from pre-existing medical conditions"
}
],
"disclaimer": "This plan is arranged by XCover.com, a trading name of Cover Genius Ltd. and underwritten by Isosceles PCC Limited.",
"disclaimer_html": "<p>This plan is arranged by XCover.com, a trading name of Cover Genius Ltd. and underwritten by Isosceles PCC Limited.</p>",
"payment_disclaimer": "",
"in_path_disclaimer": ""
},
"underwriter": {
"disclaimer": "This plan was arranged by XCover.com",
"name": "Cover Genius Singapore Pte. Ltd"
},
"claim_selector_id": "test_claim_id_123",
"pds_name": "travel_flight_cancellation_cover_v3",
"previous_policy_id": "0aa82c5d-f97a-4a4e-803f-db09f909f3b3",
"pds_version": "1.0",
"content_version": "1.0",
"pricing_expression_version": null
},
"insured": [
{
"id": "6fce9904-dd0d-44ae-b63b-c0efe034716d",
"first_name": "John",
"last_name": "Adams",
"email": "[email protected]",
"region": null,
"age": 32,
"birth_date": "1987-02-24"
}
],
"tax": {
"total_tax": 0.15,
"total_amount_without_tax": 5.18,
"total_tax_formatted": "€0.15",
"total_amount_without_tax_formatted": "€5.18",
"taxes": [
{
"tax_amount": 0.15,
"tax_code": "Tax & Surcharge (label)",
"tax_amount_formatted": "€0.15"
}
]
},
"duration": "105 00:00:00.001000",
"benefits": [
{
"description": "Full Reimbursement of Program Fee",
"limit": 50,
"limit_policy_currency": 50,
"limit_formatted": "€50.00",
"limit_policy_currency_formatted": "€50.00",
"limit_per_unit": 20,
"limit_per_unit_policy_currency": 20,
"limit_per_unit_formatted": "€20.00 ",
"limit_per_unit_policy_currency_formatted": "€20.00 ",
"excess": 100,
"excess_policy_currency": 100,
"excess_formatted": "€100.00",
"excess_policy_currency_formatted": "€100.00",
"minimum_claim_amount": 15,
"minimum_claim_amount_policy_currency": 15,
"minimum_claim_amount_formatted": "€15.00",
"minimum_claim_amount_policy_currency_formatted": "€15.00"
}
],
"commission": {
"total_commission": 0,
"total_commission_formatted": "€0.00"
},
"created_at": "2021-01-13T02:43:29.370220Z",
"confirmed_at": "2021-01-13T02:53:40.339274Z",
"updated_at": "2021-01-13T02:53:40.354372Z",
"cancelled_at": null,
"is_renewable": true,
"cover_amount": null,
"cover_amount_formatted": null,
"pds_url": "https://staging.xcover.com/en/pds/QYCTR-8GGTN-INS?policy_type=travel_flight_cancellation_cover_v1",
"attachments": [],
"files": [],
"extra_fields": {},
"discount_price": 5.33,
"discount_price_formatted": "€5.33",
"discount_amount": 0,
"discount_amount_formatted": "€0.00",
"package": {
"id": "QYCTR-8GGTN-INS",
"status": "CONFIRMED",
"currency": "EUR",
"total_price": 5.33,
"total_price_formatted": "€5.33",
"partner_transaction_id": "ABCD-EFGH-1234-5789",
"created_at": "2021-01-13T02:43:29.378873Z",
"updated_at": "2021-01-13T02:53:40.364112Z",
"pds_url": "https://staging.xcover.com/en/pds/QYCTR-8GGTN-INS",
"bundle_code": null,
"bundle_price": 5.33,
"bundle_content": {},
"bundle_price_formatted": "€5.33",
"bundle_discount_percent": 0,
"bundle_discount_amount": 0,
"bundle_discount_amount_formatted": "€0.00",
"customer": {
"id": "26d6eef1-30a2-4ed0-9c35-633a9a22dac7",
"first_name": "John",
"last_name": "Adams",
"age": null,
"email": "[email protected]",
"country": "AU",
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": null,
"phone": null,
"secondary_email": null,
"birth_date": null,
"company": null
},
"customer_region": null,
"customer_postcode": null,
"customer_country": "PH",
"policyholder": {
"first_name": "John",
"middle_name": null,
"last_name": "Adams",
"email": "[email protected]",
"phone": null,
"country": "AU",
"age": null,
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": null,
"secondary_email": null,
"birth_date": null,
"company": null,
"tax_payer_id": null
}
}}}Description: The payload is sent to the Partner whenever the Booking is cancelled through an API Request
Example:
{
"event": "BOOKING_CANCELLED",
"payload": {
"id": "1412e83c-fed7-4e64-b441-68a36cee057d",
"policy_start_date": "2021-01-18T02:43:28.352000+00:00",
"policy_end_date": "2021-05-03T02:43:28.353000+00:00",
"status": "CONFIRMED",
"price": 5.33,
"price_formatted": "€5.33",
"policy": {
"policy_type": "travel_flight_cancellation_cover",
"policy_name": "Trip Cancellation",
"policy_code": "TCAN09TL",
"policy_version": "5d606484-e029-4603-936b-0a3320ff8917",
"category": null,
"content": {
"title": "Trip Cancellation Title",
"header": "Cover for Air & Travel Costs",
"description": "If you need to cancel for medical reasons - we've got you covered. Covers prepaid travel expenses (air, hotels, cars, tours) if you need to cancel - before or after departure - due to illness to yourself or your travel group. You're also covered if your family gets sick. Claims are paid instantly.",
"optout_msg": "",
"inclusions": [
{
"title": "If you, your travel companion or close relative is injured or ill (pre or post departure)",
"description": "You're covered for your prepaid travel costs"
}
],
"exclusions": [
{
"title": "You're not covered if...",
"description": "Your cancellation claim results from pre-existing medical conditions"
}
],
"disclaimer": "This plan is arranged by XCover.com, a trading name of Cover Genius Ltd. and underwritten by Isosceles PCC Limited.",
"disclaimer_html": "<p>This plan is arranged by XCover.com, a trading name of Cover Genius Ltd. and underwritten by Isosceles PCC Limited.</p>",
"payment_disclaimer": "",
"in_path_disclaimer": ""
},
"underwriter": {
"disclaimer": "This plan was arranged by XCover.com",
"name": "Cover Genius Singapore Pte. Ltd"
},
"claim_selector_id": "test_claim_id_123",
"pds_name": "travel_flight_cancellation_cover_v3",
"previous_policy_id": "0aa82c5d-f97a-4a4e-803f-db09f909f3b3",
"pds_version": "1.0",
"content_version": "1.0",
"pricing_expression_version": null
},
"insured": [
{
"id": "6fce9904-dd0d-44ae-b63b-c0efe034716d",
"first_name": "John",
"last_name": "Adams",
"email": "[email protected]",
"region": null,
"age": 32,
"birth_date": "1987-02-24"
}
],
"tax": {
"total_tax": 0.15,
"total_amount_without_tax": 5.18,
"total_tax_formatted": "€0.15",
"total_amount_without_tax_formatted": "€5.18",
"taxes": [
{
"tax_amount": 0.15,
"tax_code": "Tax & Surcharge (label)",
"tax_amount_formatted": "€0.15"
}
]
},
"duration": "105 00:00:00.001000",
"benefits": [
{
"description": "Full Reimbursement of Program Fee",
"limit": 50,
"limit_policy_currency": 50,
"limit_formatted": "€50.00",
"limit_policy_currency_formatted": "€50.00",
"limit_per_unit": 20,
"limit_per_unit_policy_currency": 20,
"limit_per_unit_formatted": "€20.00 ",
"limit_per_unit_policy_currency_formatted": "€20.00 ",
"excess": 100,
"excess_policy_currency": 100,
"excess_formatted": "€100.00",
"excess_policy_currency_formatted": "€100.00",
"minimum_claim_amount": 15,
"minimum_claim_amount_policy_currency": 15,
"minimum_claim_amount_formatted": "€15.00",
"minimum_claim_amount_policy_currency_formatted": "€15.00"
}
],
"commission": {
"total_commission": 0,
"total_commission_formatted": "€0.00"
},
"created_at": "2021-01-13T02:43:29.370220Z",
"confirmed_at": "2021-01-13T02:53:40.339274Z",
"updated_at": "2021-01-13T02:53:40.354372Z",
"cancelled_at": null,
"is_renewable": true,
"cover_amount": null,
"cover_amount_formatted": null,
"pds_url": "https://staging.xcover.com/en/pds/QYCTR-8GGTN-INS?policy_type=travel_flight_cancellation_cover_v1",
"attachments": [],
"files": [],
"extra_fields": {},
"discount_price": 5.33,
"discount_price_formatted": "€5.33",
"discount_amount": 0,
"discount_amount_formatted": "€0.00",
"package": {
"id": "QYCTR-8GGTN-INS",
"status": "CONFIRMED",
"currency": "EUR",
"total_price": 5.33,
"total_price_formatted": "€5.33",
"partner_transaction_id": "ABCD-EFGH-1234-5789",
"created_at": "2021-01-13T02:43:29.378873Z",
"updated_at": "2021-01-13T02:53:40.364112Z",
"pds_url": "https://staging.xcover.com/en/pds/QYCTR-8GGTN-INS",
"bundle_code": null,
"bundle_price": 5.33,
"bundle_content": {},
"bundle_price_formatted": "€5.33",
"bundle_discount_percent": 0,
"bundle_discount_amount": 0,
"bundle_discount_amount_formatted": "€0.00",
"customer": {
"id": "26d6eef1-30a2-4ed0-9c35-633a9a22dac7",
"first_name": "John",
"last_name": "Adams",
"age": null,
"email": "[email protected]",
"country": "AU",
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": null,
"phone": null,
"secondary_email": null,
"birth_date": null,
"company": null
},
"customer_region": null,
"customer_postcode": null,
"customer_country": "PH",
"policyholder": {
"first_name": "John",
"middle_name": null,
"last_name": "Adams",
"email": "[email protected]",
"phone": null,
"country": "AU",
"age": null,
"address1": null,
"address2": null,
"city": null,
"postcode": null,
"region": null,
"secondary_email": null,
"birth_date": null,
"company": null,
"tax_payer_id": null
}
}}}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",
"end_date": "2019-05-25T13:00:00Z",
"price": 110.41,
"period": "quarterly",