Holiday Extras API

Insurance Create Policy

API Docs > product:Insurance

Create Insurance Policy Request

This endpoint will create a new insurance policy.

Please note: we do not have a test environment for insurance, so you will be unable to use /sandbox/. To make test policies you will need to follow these rules:

  1. Make the policy more than 3 months from the search date;
  2. Do not have more than 3 test policies live at any one point;
  3. Please advise your Account Manager so the test policies can be cancelled down in our system.

Failing to notify us of test policies being made will result in your account being charged for these.




To create an insurance policy, the endpoint to use is (where CertificateRef is returned in the options response):

Request Parameters

NB: All parameter names are case sensitive.

Name Data Type Format Mandatory? Additional Information
ABTANumber String [A-Z0-9] 5 chars Y This is also known as an ‘agent code’.
This will be confirmed to you by your Account Manager during set up.
Password String [A-Z0-9] 5 chars Y Password required for retail agent requests - intermediaries do not require a password.
This will be confirmed to you by your Account Manager during set up.
key String [A-Z] Y This will be assigned to you by your Account Manager during set up.
token String [0-9] 9 chars Y Please see user token endpoint for details of how to generate a token.
Address[] String [0-9] 20 chars Y First line of address (house name / number and road) of customer.
If you require more than 1 address line, then you can replicate this field and increment the number in square brackets, i.e. “Address[1]” for address line 2, and so on.
Town String [0-9] 4 chars Y Town of address.
County String [0-9] 4 chars Y County of address.
PostCode String [0-9] 4 chars Y Post code of address.
Email String [0-9] 4 chars Y Customer’s email.
DayPhone Integer [0-9] 15 chars max N The customer’s telephone number.
option Array [A-Z0-9] N Per policy options require schemeoptionID, optionRateID, optionPrice and optionIPT. Per person options also require the CertificateClientID of the person they are for. Per person options can be submitted multiple times with different CertificateClientIDs. This should be sent as a multidimensional array/hash. See the worked examples below for more information.

Create Insurance Policy Response

The create insurance policy response will return details of the insurance policy booked, and any options.

For a detailed explanation of the fields returned, please see below:

Field Additional Information
familyGroupID TBC
familyGroupName TBC
keyFactsDocName TBC
policyWordingDocName TBC
SourceSystem TBC
ResidenceID TBC
CostofHoliday TBC
QuoteExpired TBC
FriendlyName TBC
cover There are three elements to this: cancellation, medical and possessions. Each block will return details on the limits and excesses for each type of cover.
Scheme This block provides a summary of the scheme details, including links to the policy wording and key facts. It also returns the PolicyNumber, which is required in all communication with us post booking, including where the customer needs to make a claim.
PolicyOptions TBC
ClientDetails This block returns the address and contact details for the customer.
Itinerary This block shows a summary of the date and destinations covered by the policy.
Pricing This block provides a breakdown of the pricing elements, including gross, net and IPT.
People This block returns details of the individuals under the policy’s cover (as provided in previous requests).
API_Header The API returns every parameter and value you sent in the previous request.


In the UK, we are PCI DSS compliant and so we do not accept customers’ payment details being passed to us via the API. Further details can be found in our section on Payment.

Please contact your Account Manager if you have any questions concerning payment.

Policy Wording and Key Facts

It is mandatory that the customer has access to the both the Policy Wording and the Key Facts document, as insurance is a financial product and subject to additional regulations around its point of sale. Both of these documents are available in the insurance schemes availability response and create insurance policy response (pre- and post-booking).

Worked Examples

Below are worked examples of both the request and response for creating an insurance policy.

Create Insurance Policy Request
      <Address[]>1 Test Street</Address[]>
      <PostCode>TE1 STZ</PostCode>

Create Insurance Policy Response

<?xml version="1.0" ?>
            <section>Cancellation Cover</section>
            <section>Medical Emergency Expenses</section>
            <section>Personal possessions</section>
        <schemeName>OTA Bronze A2B</schemeName>
        <destinationName>Europe (exc Spain, Cyprus, Malta, Turkey and Greece)</destinationName>
            <Address>1 Test Street</Address>
            <Postcode>TE1 STZ</Postcode>