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 the data with your API signing key using HmacSHA1 algorithm.
  3. Encode the resulting string (the signature) in Base64 and do URL encoding of the result.
  4. Put the resulting signature in the Authorization header and add

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.testing_api_key,
    apiSecret = environment.testing_api_secret,
    date = (new Date()).toUTCString(),
    signatureContentString = 'date: ' + date,
    signatureString = CryptoJS.HmacSHA1(signatureContentString, apiSecret).toString(CryptoJS.enc.Base64),
    authHeader = 'Signature keyId="' + apiKey + '",algorithm="hmac-sha1",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.

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.

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 are listed below:

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",
        "end_date": "2019-05-25T13:00:00Z",
        "price": 110.41,
        "period": "quarterly",
        "created_at": "2018-11-21T04:15:12.175468Z",
        "notification_date": "2018-11-22T00:21:41Z",
        "due_date": "2019-02-25T13:00:00Z",
        "expiry_date": "2018-11-21T22:56:01Z"
    }
}

renewal.due_date

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_date",
    "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",
        "end_date": "2019-05-25T13:00:00Z",
        "price": 110.41,
        "period": "quarterly",
        "created_at": "2018-11-21T04:15:12.175468Z",
        "notification_date": "2018-11-22T00:21:41Z",
        "due_date": "2018-11-22T00:23:16Z",
        "expiry_date": "2018-11-21T22:56:01Z"
    }
}

renewal.expired

Description: Sent on the renewal expiry date, the customer policy is considered canceled 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",
        "end_date": "2019-05-25T13:00:00Z",
        "price": 110.41,
        "period": "quarterly",
        "created_at": "2018-11-21T04:15:12.175468Z",
        "notification_date": "2018-11-22T00:21:41Z",
        "due_date": "2018-11-22T00:23:16Z",
        "expiry_date": "2018-11-22T00:24:20Z"
    }
}

booking.updated

Description: Sent to the Partner whenever the Booking is Updated through an API Request

Example:

{  
   'event':'booking.update',
   'payload':{  
      'old':{  
         'id':'8QR94-VUMQC-INS',
         'status':'CONFIRMED',
         'quotes':[  
            {  
               'id':'1faf57b7-29bd-48ba-9cb7-30502bca734b',
               'policy_start_date':'2019-03-20T10:40:30.127726Z',
               'policy_end_date':None,
               'status':'CONFIRMED',
               'price':'2.500000',
               'price_formatted':'A$\xa02.50',
               'discounted_price':'2.500000',
               'discounted_price_formatted':'A$\xa02.50',
               'policy':{  
                  'policy_type':'test_policy_type_0',
                  'policy_name':'PolicyVersion 0',
                  'policy_code':'DFKE43NM',
                  'policy_version':'f92e6926-5abe-4399-a772-15f9680437d3',
                  'content':{...},
                  'underwriter':{  
                     'disclaimer':''
                  }
               },
               'insured':[  
                  {  
                     'id':'b0e60d4d-d43f-4586-ac3a-efef50a9cffd',
                     'first_name':'test_name_1',
                     'last_name':'test_name_3',
                     'email':'[email protected]',
                     'country':'AU'
                  }
               ],
               'tax':{  
                  'total_tax':'0.00',
                  'total_amount_without_tax':'2.50',
                  'total_tax_formatted':'A$\xa00.00',
                  'total_amount_without_tax_formatted':'A$\xa02.50',
                  'taxes':[  

                  ]
               },
               'duration':None,
               'sub_limits':[  

               ],
               'commission':{  
                  'total_commission':'0.00',
                  'total_commission_formatted':'A$\xa00.00'
               },
               'created_at':'2019-03-20T05:40:30.881689Z',
               'confirmed_at':'2019-03-20T05:40:31.190425Z',
               'updated_at':None,
               'cancelled_at':None,
               'is_renewable':False,
               'cover_amount':'A$\xa0500.00',
               'pending_renewal':None,
               'can_be_cancelled':True
            }
         ],
         'currency':'AUD',
         'total_price':'2.50',
         'total_price_formatted':'A$\xa02.50',
         'bundle_price':'2.500000',
         'bundle_price_formatted':'A$\xa02.50',
         'bundle_discount_percent':0,
         'bundle_discount_amount':'0.00',
         'bundle_discount_amount_formatted':'A$\xa00.00',
         'created_at':'2019-03-20T05:40:30.624910Z',
         'updated_at':'2019-03-20T05:40:31.320806Z',
         'pds_url':'http://127.0.0.1:8001/pds/8QR94-VUMQC-INS',
         'coi':{  
            'url':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS?security_token=aKMWa-3xknm-8y79O-qmhsp',
            'pdf':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS.pdf?security_token=aKMWa-3xknm-8y79O-qmhsp'
         },
         'policyholder':{  
            'first_name':'Jacqueline',
            'last_name':'Bennett',
            'email':'[email protected]',
            'country':'AU'
         },
         'total_tax':'0.00',
         'total_premium':'2.50'
      },
      'new':{  
         'id':'8QR94-VUMQC-INS',
         'status':'CONFIRMED',
         'quotes':[  
            {  
               'id':'1faf57b7-29bd-48ba-9cb7-30502bca734b',
               'policy_start_date':'2019-03-20T10:40:30.127726Z',
               'policy_end_date':None,
               'status':'CONFIRMED',
               'price':'2.500000',
               'price_formatted':'A$\xa02.50',
               'discounted_price':'2.500000',
               'discounted_price_formatted':'A$\xa02.50',
               'policy':{  
                  'policy_type':'test_policy_type_0',
                  'policy_name':'PolicyVersion 0',
                  'policy_code':'DFKE43NM',
                  'policy_version':'f92e6926-5abe-4399-a772-15f9680437d3',
                  'content':{  
                     'section_header':'',
                     'description':'',
                     'inclusions':[  

                     ],
                     'exclusions':[  

                     ]
                  },
                  'underwriter':{  
                     'disclaimer':''
                  }
               },
               'insured':[  
                  {  
                     'id':'b0e60d4d-d43f-4586-ac3a-efef50a9cffd',
                     'first_name':'test_name_1',
                     'last_name':'test_name_3',
                     'email':'[email protected]',
                     'country':'AU'
                  }
               ],
               'tax':{  
                  'total_tax':'0.00',
                  'total_amount_without_tax':'2.50',
                  'total_tax_formatted':'A$\xa00.00',
                  'total_amount_without_tax_formatted':'A$\xa02.50',
                  'taxes':[  

                  ]
               },
               'duration':None,
               'sub_limits':[  

               ],
               'commission':{  
                  'total_commission':'0.00',
                  'total_commission_formatted':'A$\xa00.00'
               },
               'created_at':'2019-03-20T05:40:30.881689Z',
               'confirmed_at':'2019-03-20T05:40:31.190425Z',
               'updated_at':'2019-03-20T05:40:31.731769Z',
               'cancelled_at':None,
               'is_renewable':False,
               'cover_amount':'A$\xa0500.00',
               'pending_renewal':None,
               'can_be_cancelled':True
            }
         ],
         'currency':'AUD',
         'total_price':'2.50',
         'total_price_formatted':'A$\xa02.50',
         'bundle_price':'2.500000',
         'bundle_price_formatted':'A$\xa02.50',
         'bundle_discount_percent':0,
         'bundle_discount_amount':'0.00',
         'bundle_discount_amount_formatted':'A$\xa00.00',
         'created_at':'2019-03-20T05:40:30.624910Z',
         'updated_at':'2019-03-20T05:40:31.839587Z',
         'pds_url':'http://127.0.0.1:8001/pds/8QR94-VUMQC-INS',
         'coi':{  
            'url':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS?security_token=aKMWa-3xknm-8y79O-qmhsp',
            'pdf':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS.pdf?security_token=aKMWa-3xknm-8y79O-qmhsp'
         },
         'policyholder':{  
            'first_name':'Jacqueline',
            'last_name':'Bennett',
            'email':'[email protected]',
            'country':'AU'
         },
         'total_tax':'0.00',
         'total_premium':'2.50'
      }
   }
}

booking.cancelled

Description: Sent to the Partner whenever the Booking is Cancelled through an API Request

Example:

{  
   'event':'booking.cancellation',
   'payload':{  
      'old':{  
         'id':'8QR94-VUMQC-INS',
         'status':'CONFIRMED',
         'quotes':[  
            {  
               'id':'1faf57b7-29bd-48ba-9cb7-30502bca734b',
               'policy_start_date':'2019-03-20T10:40:30.127726Z',
               'policy_end_date':None,
               'status':'CONFIRMED',
               'price':'2.500000',
               'price_formatted':'A$\xa02.50',
               'discounted_price':'2.500000',
               'discounted_price_formatted':'A$\xa02.50',
               'policy':{  
                  'policy_type':'test_policy_type_0',
                  'policy_name':'PolicyVersion 0',
                  'policy_code':'DFKE43NM',
                  'policy_version':'f92e6926-5abe-4399-a772-15f9680437d3',
                  'content':{...},
                  'underwriter':{  
                     'disclaimer':''
                  }
               },
               'insured':[  
                  {  
                     'id':'b0e60d4d-d43f-4586-ac3a-efef50a9cffd',
                     'first_name':'test_name_1',
                     'last_name':'test_name_3',
                     'email':'[email protected]',
                     'country':'AU'
                  }
               ],
               'tax':{  
                  'total_tax':'0.00',
                  'total_amount_without_tax':'2.50',
                  'total_tax_formatted':'A$\xa00.00',
                  'total_amount_without_tax_formatted':'A$\xa02.50',
                  'taxes':[  

                  ]
               },
               'duration':None,
               'sub_limits':[  

               ],
               'commission':{  
                  'total_commission':'0.00',
                  'total_commission_formatted':'A$\xa00.00'
               },
               'created_at':'2019-03-20T05:40:30.881689Z',
               'confirmed_at':'2019-03-20T05:40:31.190425Z',
               'updated_at':None,
               'cancelled_at':None,
               'is_renewable':False,
               'cover_amount':'A$\xa0500.00',
               'pending_renewal':None,
               'can_be_cancelled':True
            }
         ],
         'currency':'AUD',
         'total_price':'2.50',
         'total_price_formatted':'A$\xa02.50',
         'bundle_price':'2.500000',
         'bundle_price_formatted':'A$\xa02.50',
         'bundle_discount_percent':0,
         'bundle_discount_amount':'0.00',
         'bundle_discount_amount_formatted':'A$\xa00.00',
         'created_at':'2019-03-20T05:40:30.624910Z',
         'updated_at':'2019-03-20T05:40:31.320806Z',
         'pds_url':'http://127.0.0.1:8001/pds/8QR94-VUMQC-INS',
         'coi':{  
            'url':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS?security_token=aKMWa-3xknm-8y79O-qmhsp',
            'pdf':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS.pdf?security_token=aKMWa-3xknm-8y79O-qmhsp'
         },
         'policyholder':{  
            'first_name':'Jacqueline',
            'last_name':'Bennett',
            'email':'[email protected]',
            'country':'AU'
         },
         'total_tax':'0.00',
         'total_premium':'2.50'
      },
      'new':{  
         'id':'8QR94-VUMQC-INS',
         'status':'CONFIRMED',
         'quotes':[  
            {  
               'id':'1faf57b7-29bd-48ba-9cb7-30502bca734b',
               'policy_start_date':'2019-03-20T10:40:30.127726Z',
               'policy_end_date':None,
               'status':'CANCELLED',
               'price':'2.500000',
               'price_formatted':'A$\xa02.50',
               'discounted_price':'2.500000',
               'discounted_price_formatted':'A$\xa02.50',
               'policy':{  
                  'policy_type':'test_policy_type_0',
                  'policy_name':'PolicyVersion 0',
                  'policy_code':'DFKE43NM',
                  'policy_version':'f92e6926-5abe-4399-a772-15f9680437d3',
                  'content':{  
                     'section_header':'',
                     'description':'',
                     'inclusions':[  

                     ],
                     'exclusions':[  

                     ]
                  },
                  'underwriter':{  
                     'disclaimer':''
                  }
               },
               'insured':[  
                  {  
                     'id':'b0e60d4d-d43f-4586-ac3a-efef50a9cffd',
                     'first_name':'test_name_1',
                     'last_name':'test_name_3',
                     'email':'[email protected]',
                     'country':'AU'
                  }
               ],
               'tax':{  
                  'total_tax':'0.00',
                  'total_amount_without_tax':'2.50',
                  'total_tax_formatted':'A$\xa00.00',
                  'total_amount_without_tax_formatted':'A$\xa02.50',
                  'taxes':[  

                  ]
               },
               'duration':None,
               'sub_limits':[  

               ],
               'commission':{  
                  'total_commission':'0.00',
                  'total_commission_formatted':'A$\xa00.00'
               },
               'created_at':'2019-03-20T05:40:30.881689Z',
               'confirmed_at':'2019-03-20T05:40:31.190425Z',
               'updated_at':'2019-03-20T05:40:31.731769Z',
               'cancelled_at':None,
               'is_renewable':False,
               'cover_amount':'A$\xa0500.00',
               'pending_renewal':None,
               'can_be_cancelled':True
            }
         ],
         'currency':'AUD',
         'total_price':'2.50',
         'total_price_formatted':'A$\xa02.50',
         'bundle_price':'2.500000',
         'bundle_price_formatted':'A$\xa02.50',
         'bundle_discount_percent':0,
         'bundle_discount_amount':'0.00',
         'bundle_discount_amount_formatted':'A$\xa00.00',
         'created_at':'2019-03-20T05:40:30.624910Z',
         'updated_at':'2019-03-20T05:40:31.839587Z',
         'pds_url':'http://127.0.0.1:8001/pds/8QR94-VUMQC-INS',
         'coi':{  
            'url':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS?security_token=aKMWa-3xknm-8y79O-qmhsp',
            'pdf':'http://127.0.0.1:8001/coi/8QR94-VUMQC-INS.pdf?security_token=aKMWa-3xknm-8y79O-qmhsp'
         },
         'policyholder':{  
            'first_name':'Jacqueline',
            'last_name':'Bennett',
            'email':'[email protected]',
            'country':'AU'
         },
         'total_tax':'0.00',
         'total_premium':'2.50'
      }
   }
}