Webservices 2.0 Technical Documentation

Last Updated: March 2023, Documentation Revision: 4.0

Contents

1. Introduction
2. General Design
3. Common Workflows
4. Booking, Journey and Location Types
5. Availability and Pricing
6. Pickup Date/Time Calculation
7. Payment
8. Dictionary

Introduction

This document gives an overview of the Holiday Taxis Web Services 2.0 API. It is aimed at developers and technical personnel who will be integrating the API.

Holiday Taxis Web Services 2.0 is a JSON and XML API for travel agents and partners to search for products, and create and manage bookings.

The details of the individual requests and response formats are available on a separate page, automatically generated from an OpenAPI 3.1 Description. For other information and the most up-to-date version of this document, check the Holiday Taxis Developer Portal.

For support enquiries, and information on how to set up a test account, please email us on salessupport@holidaytaxis.com.

General Design

Request Headers

Authentication

All requests must be authenticated by including an HTTP header named API_KEY, with a value which will be provided to you. Note that you will have a different API key for the Staging (test) environment and the Production environment.

If you wish to make a booking on account, you will need to pass an AGENT_REF header in your Create Booking account, which specifies the agency to be invoiced.

Request and Response Format

The API supports both JSON and XML requests and responses. To specify your preferred format, you must include an Accept HTTP header of either application/json or application/xml. Note that the body of your request (where applicable) should be in the same format as you have requested for the response (e.g. if you specify Accept: application/json, your request must also be in JSON format).

Internationalisation

Most content intended for display is available in multiple languages, which can be selected using a Accept-Language header. The language code should be specified as a two-letter code according to the ISO 639-1 standard.

Please contact Holiday Taxis to confirm the list of available languages. If no Accept-Language header is included, or the requested language is not available, English will be used instead. Individual strings will also be returned in English where no translation is available in the requested language.

By default, prices are formatted based on the output language, e.g. 1,234.00 for English and 1.234,00 for French. To disable this behaviour, send an HTTP header of DISABLE_NUMBER_FORMATTING: 1. This will format all prices with no thousand separator, and '.' as decimal separator, e.g. 1234.00.

HTTP Status Codes

The API will return varying HTTP Status Codes depending on how successful the request was. The below table explains what to look out for when consuming the API.

Status Code	Description
200	OK. The request was successful, a response is included in the HTTP Body if the end point sends a response.
207	Multi-Status. The request was partially successful, the response included in the HTTP Body will also include an 'errors' block which attention should be given to.
204	No Content. The requested resource could not be found. e.g. The booking doesn't exist, or no bookings/products matched the search parameters.
400	Bad Request. The request had one or more errors in it. The response included in the HTTP Body will have an 'errors' block which attention should be given to.
401	Unauthorized. The API Key sent is either invalid, or the request was sent from an IP Address which has not been whitelisted. The response included in the HTTP Body will have an 'errors' block which attention should be given to.
404	Not Found. The requested URL was not recognised by the API.

Errors

The API can return varying error messages depending on the content of the request. They will be contained inside an 'errors' block in the response and each error will consist of the elements in the below table.

Element	Description	Always Provided
message	A technical error message for use by the developer integrating the API. This will contain information such as which field was invalid/missing, validation errors and other technical issues with the request.	Yes
title	A brief, user-friendly description of the error. Suggested use would be as the title to an error 'alert' box.	No
display	A more detailed user-friendly error message. Suggested use would be the error message displayed to the end user.	No

Dates and Times

Most dates and times in input and output are represented in the format YYYY-MM-DD\Thh:mm:ss, e.g. 2018-08-20T14:00:00, and must not include a time zone.

Times related to the customer's travel (e.g. departure, arrival, and pickup times) are treated as local time in the time zone where the transfer is located.

Times referring to the creation, amendment and cancellations of bookings are treated as having no location and use the time zone UTC (+00:00).

Prices

Prices are represented as strings with a fixed number of decimals, appropriate for the currency in use (usually 2). See the note above about how the DISABLE_NUMBER_FORMATTING header affects these.

Unless otherwise indicated in the documentation, all prices in a particular request or response use the same currency, which will normally be the currency configured for the billing account.

Common Workflows

Search for Products and Create a Booking

To create a new booking, you must first perform a search, to confirm the available products and their prices. See Booking, Journey and Location Types for the different options for searching.

Searches and bookings can be made for a single transfer journey, but it is often convenient to specify a pair of journeys as one booking. A common scenario is a customer arriving at an airport, and wanting a transfer to their hotel; then at the end of their stay, returning to the airport. This can be booked as follows:

1. Perform a return search, specifying the airport IATA code, hotel location, outbound flight arrival time, and inbound flight departure time. For example: GET /products/search/from/IATA/PMI/to/GIATA/10448/travelling/2020-08-20T14:00:00/returning/2020-08-27T14:00:00/adults/2
2. This will return two sets of products, one for each direction. You may wish to present these as pairs matched on Product Type and capacity (minpax and maxpax). Note that the matching products may or may not have the same productid.
3. The search results also include Optional Extras, such as child seats and additional baggage. Note that in some destinations, use of child seats is a legal requirement, so we recommend showing these options to the customer to avoid later queries.
4. To book, additional information is required depending on the pickup and drop-off points, as discussed under Booking, Journey and Location Types. In this example, this will be the flight number for each flight. If you are not using a hotel code, the full hotel address is also required at this stage.
5. The booking is then made using the POST /bookings/create operation. In this example, the request will include two blocks in the transfers section, one for each journey.
6. If you have agreed to pay on account, you must send an AGENT_REF HTTP header with the request, and set paymenttype to INV. Otherwise, you will need to provide details for a supported payment method as discussed under Payment.
7. If the booking is processed successfully, the response will confirm the details of the booking, including a unique Booking Reference, which can be used to retrieve and modify the booking later.

Manage an Existing Booking

• To retrieve the details of an existing booking, use the GET /bookings/{bookingRef} operation with the Booking Reference from the initial Create Booking response. The response is in the same format as the initial Create Booking response, and is also returned from the Amend and Cancel operations.
• The booking can be amended using the POST /bookings/amend/{bookingRef} operation. Booking amendments are restricted to elements which will not affect the product or price of the booking, therefore changes to passenger/vehicle numbers and vehicle types cannot be amended. You will be able to update the passenger's name and contact details, and details of inbound and onward travel (such as flight numbers and travel dates). However, if the new flight date/time for either leg of the transfer has a different price to the original then the amendment will not be possible.
• A complete booking can be cancelled using the DELETE /bookings/cancel/{bookingRef} operation. Alternatively, you can cancel a single journey within a booking, using the DELETE /bookings/cancel/{bookingRef}/{transferId} operation. You can find the transferid for each journey in the Create Booking or Get Booking response. Only journeys which have not yet travelled can be cancelled, and you may be charged a cancellation fee up to 100% of the original price for cancelling close to the travel date.

Working with Metadata

The API provides several operations to fetch information about Holiday Taxis products and internal identifiers. Note that this data changes infrequently, and we strongly advise caching the results in your own system, and updating no more than twice a day.

In search results and booking responses, products are associated with a Product Type, indicating the type of vehicle and service. Details of these, including descriptions and image URLs, can be fetched using the GET /products/getproducttypes operation, and looked up using the producttypeid.

The majority of Holiday Taxis products are priced based on a route from a "gateway" (an airport, port, train or bus station) to a "resort" (a named geographic area).

• The GET /products/getalldestinations operation lists every gateway and resort recognised by the Holiday Taxis system, with their name, internal identifier, and standard IATA code where relevant.
• The GET /products/getallroutes/{fromTypeCode}/{fromCode} operation can be used with an internal Holiday Taxis identifier, directly with an IATA code, or using the latitude and longitude of a hotel or other address. It will return the routes that are supported from or to that location.
• The GET /products/resorts/areas operation returns a list of Holiday Taxis resorts with one or more shapes in WKT format which describe the geographic areas included in that resort. The resort is represented using our internal identifier which can be obtained using the GET /products/getallroutes or GET /products/getalldestinations operations. GET /products/getallroutes will return this as resortid and GET /products/getalldestinations will return it as destinationcode where destinationtypecode = "RST".

Booking, Journey and Location Types

Booking Types (Direction of Travel)

To search for and book a Holiday Taxis product, you must specify the location where the customer wishes to be picked up, the location where they wish to be dropped off, and the time when you want the transfer to take place. Journeys are grouped into two "booking types", indicated by a bookingtypeid field, as follows.

Booking Type	ID	Description	Date to Provide	Pickup Time
Outbound	2 or 7	The customer is arriving at an airport or other gateway, and travelling to a hotel or address.	Arrival time at the airport or gateway	The transfer provider will be waiting at the gateway when the customer arrives.
Inbound	3 or 8	The customer wishes to be picked up at a hotel or address and taken to an airport or other gateway in time for a flight or onward journey.	Departure time of the flight or onward journey	Calculated based on estimated journey time and check-in time; see Pickup Date/Time Calculation

A return booking generally consists of one journey with bookingtypeid 2 and one with bookingtypeid 3, or one with bookingtypeid 7 and one with bookingtypeid 8.

When both arrival and departure points are gateways (for example a transfer between an Airport and a Port), the journeys are still given a booking type. Pickup times are based on the arrivaldatetime for bookingtypeid 2 or 7, and the departuredatetime for bookingtypeid 3 or 8 (adjusted to allow for transfer time and check-in time).

Product IDs used in search results are unique for a product type, supplier, and travel date combination, but not direction. For bookingtypeid 2 and 3, they are related to the contracts we have with the supplier and change from one supplier to the next; for bookingtypeid 7 and 8, they are dynamically allocated and only valid for a limited time after a search. This means the same product type may or may not have the same Product IDs for the outbound and inbound transfer in a return search.

Location codes

Searches and bookings can specify the locations for pick up and drop off locations using several formats. We recommend that wherever possible you use IATA codes for airports, and either GIATA hotel codes or latitude and longitude (code type GEO) for accommodation.

Code Type	Format	Description
IATA	3-letter code	IATA standard airport identifier codes
GIATA	integer	Hotel identifier issued by GIATA
GEO	latitude,longitude	Geographic location in the format 'latitude,longitude', e.g. 50.821066,-0.141306
IFF	integer	Hotel identifier issued by IFF
TTI	integer	Hotel identifier issued by TTI
ATLAS	integer	HotelBeds hotel identifier
PRT	integer	Holiday Taxis internal identifier for a port
STN	integer	Holiday Taxis internal identifier for a train station
BUS	integer	Holiday Taxis internal identifier for a bus station
RST	integer	Holiday Taxis internal identifier for a resort. If you are unable to provide a hotel code or exact co-ordinates for a destination, a RST code can be used instead. You will still need to provide an address for RST bookings, and it may cause later issues if the address is outside the resort area.

For more information on internal Holiday Taxis identifiers, see the section on Working with Metadata.

Supported journey types

The following table lists the combinations of location type which are supported by Holiday Taxis. Note that it is not currently possible to book a transfer from hotel to hotel, or address to address.

From	Using code type	To	Using code type	Booking type
Airport	IATA	Hotel or Address	GIATA, GEO, ATLAS, TTI	Outbound
Airport	IATA	Port	PRT	Varies; check bookingtypeid in response
Airport	IATA	Train station	STN	Varies; check bookingtypeid in response
Airport	IATA	Bus station	BUS	Varies; check bookingtypeid in response
Airport	IATA	Resort	RST	Outbound
Hotel or Address	GIATA, GEO, ATLAS, TTI	Airport	IATA	Inbound
Hotel or Address	GIATA, GEO, ATLAS, TTI	Port	PRT	Inbound
Hotel or Address	GIATA, GEO, ATLAS, TTI	Train Station	STN	Inbound
Hotel or Address	GIATA, GEO, ATLAS, TTI	Bus Station	BUS	Inbound
Port	PRT	Airport	IATA	Varies; check bookingtypeid in response
Port	PRT	Hotel or Address	GIATA, GEO, ATLAS, TTI	Outbound
Train station	STN	Airport	IATA	Varies; check bookingtypeid in response
Train station	STN	Hotel or Address	GIATA, GEO, ATLAS, TTI	Outbound
Bus station	BUS	Airport	IATA	Varies; check bookingtypeid in response
Bus station	BUS	Hotel or Address	GIATA, GEO, ATLAS, TTI	Outbound
Resort	RST	Airport	IATA	Inbound

Transfers From/To Details Block

When creating a booking, additional details must be included in the fromdetails and todetails blocks based on the type of location. The correct block will be listed in the search block in search results, or determined from the table below.

Location Type	Search Location Type Codes	Included Block	Notes
Airport	IATA, AIR	flight
Port	PRT	cruise
Train station	STN	train
Bus station	BUS	bus
Hotel	GIATA, TTI, IFF, ATLAS	accommodation	Specify 'codetype' and 'code'
Address	GEO, RST	accommodation	Specify at least 'name' and 'addressline1'

Note: fields relating to the incorrect location type in the request (e.g. shipname sent in a flight block) will be ignored, but may not return an error message.

Availability and Pricing

Black Outs

Certain products and routes have 'black out' periods. During these times the products will not be available for booking and will not return for product searches that fall within this period.

Night Rates

Some products and routes will have night rates, these products are generally more expensive to book during these periods. Night rates usually apply between 11pm-8am. Products with night rates can be mixed and matched in the same booking. If a product search is returned without night rates but the booking request is made during a night rate period, the booking will fail.

It is very important that you search with the correct travel times to ensure night rates are included at the time of search. This will avoid an incorrect pricing error at the time of booking.

Schedules

Some products and routes will have schedules, typically shared shuttles as they must leave the start point at a set time. These products will require the customer to check the scheduled time of the transfer.

Pickup Date/Time Calculation

You do not need to send pick-up times in your booking request. Pick-up times are based on your specified arrival/departure times as follows:

All transfers from airport / port / station (booking type 2 or 7)

Any pick-up times sent will be ignored. Our suppliers will use your arrival date/times to ensure they collect the passenger after their arrival at the pick-up location.

Private transfers from accommodation (booking type 3 or 8, perperson=0)

Please use the pick-up time specified in our booking response on your passenger documentation. We have calculated this based on the flight/cruise/bus/train departure time you have specified, our estimated travel time, and our recommended check-in time at the destination.

You may send a custom pick-up time to reduce or increase the passenger's wait time at the destination, but we do not recommend this. If you do so this is at your risk, and we cannot guarantee the passenger will arrive in time to meet their onward flight/ship/train/bus. Please speak to your account manager if you wish to use this option.

Shared / shuttle transfers from accommodation (booking type 3 or 8, perperson=1)

Passengers will need to reconfirm their pick-up time with our suppliers before the travel date, as pick-up times depend on the number of stops the vehicle will be making on the day of travel. Our booking response will indicate whether reconfirmation is required (using reconfirmationrequired). It will be clear in our transfer instructions how a passenger can reconfirm their pick-up time with the supplier. These will be in our booking response You should include these instructions on your passenger documentation, and therefore pick-up times for shuttles should not be included on your passenger documentation.

Payment

The API currently supports three methods of payment, which are selected using codes in the 'paymenttype' field in the request:

INV

Payment via Invoice / On Account. This is only available if the agency creating the booking (as indicated in the 'AGENT_REF' header) has an active invoicing agreement with Holiday Taxis.

CARD

Immediate payment using a credit or debit card. This is available for all bookings. In order to comply with EU regulations, any booking where the customer is within the EU or UK must include 3-D Secure authentication details, as discussed below.

ELV

Payment via the ELV or SEPA Direct Debit schemes. This option is only available when paying in Euros, and is not offered on all products due to the risk of fraudulent or reversed payments, or for bookings travelling within 14 days.

3-D Secure Implementation

In order to comply with the EU mandate for Strong Customer Authentication, it is required that all UK/EU card payments are pre-authenticated using 3-D Secure 2. If your agency setting is set to card payment, this will be required.

1. You will need to send the card and transaction details to a payment service provider who can act as a "3DS Server" or "MPI". This will perform a risk assessment based on the details you provide, but will not reserve any funds.
2. If requested by the card issuer, you will need to display an authentication challenge to the customer.
3. If the challenge is completed successfully, or the card issuer decides no challenge is required, the 3DS Server will return a set of fields confirming the status of the transaction.
4. These details must then be included in the New Booking request in the 'auth3ds' block documented below.
5. Holiday Taxis will then pass these to our own payment service provider, and take payment for the booking directly from the card presented.

Payment-Related Errors

As well as general validation and system errors regarding the booking, there are additional errors relating to specific payment types which your application should handle.

Error Code	Description	Suggested Action
invalidparameter_general_paymenttype or invalid_agent_payment_type	The payment type you have selected is not supported for the agency or booking selected. For instance, you have requested an Invoice booking, but do not have an active invoicing agreement.	Contact your account manager at Holiday Taxis to confirm which payment types are available to you.
paymenterror	The request passed validation, but there was an error while processing the payment.	Contact Holiday Taxis to check the status of the booking. Do not re-attempt the booking or advise the customer to do so, as this may result in duplicate bookings or payments.
card_authentication_required	No 3-D Secure authentication details were provided, but regulations or the issuing bank of the card mean that payment cannot proceed without them.	If you have integrated a 3-D Secure process, ensure you have populated the 'auth3ds' block correctly in your request. If you have not implemented the process, you will need to use an alternative means of payment.
card_authentication_refused	The 3-D Secure authentication details provided were rejected by the issuing bank.	Check that the correct details were included in the '3dsauth' block. Ensure you are rejecting payment details where the 3-D Secure check has failed.

Dictionary

The below dictionaries display the possible values for particular fields:

Transfer Status

Name	Description	Effective Status
PCON	Pending Booking Voucher - the booking is confirmed from a Holiday Taxis and Client point of view. The client will have received confirmation and a booking voucher. This is an internal code that tells us we are waiting for our supplier to physically acknowledge the booking. Once this is done the status returned for any further queries will be ACON. Please note that in our staging environment bookings will never show as ACON.	Booked
ACON	Booking Voucher Approved - booking confirmed	Booked
PAMM	Pending Amendment - Internal code indicating waiting for supplier to approve	Booked (amended)
AAMM	Amendment Approved - amendment approved by supplier	Booked (amended)
PCAN	Pending Cancellation - the booking is cancelled from a Holiday Taxis and Client point of view. The client will have received notification of cancellation and a refund will have been requested from the payment provider. This is an internal code that tells us we are waiting for our supplier to physically acknowledge cancellation. Once this is done the status returned for any further queries will be ACAN.	Cancelled
ACAN	Cancellation Approved - booking cancelled	Cancelled
PPAY	Pending Payment - internal code indicating we are waiting for payment completion	Booked
PINF	Pending Information - additional information required on booking	Booked

Product Categories

Name	Description
Shuttle	A standard shared shuttle service
Taxi	A small private vehicle, typically a 1-4 passenger capacity
Minibus	A mid-range private vehicle, typically 5-20 passenger capacities are available
Coach	A large private vehicle
Luxury	A more expensive private vehicle, including limousines and helicopters
Green	Environmentally friendly vehicles
Wheelchair Adapted	Vehicles specifically adapted to allow passengers in wheelchairs to board easily
Non Refundable	Products which are exempt from our standard refund policy

Payment Type Names

Name	Description
Card	Credit or debit card
ELV	ELV or SEPA Direct Debit
Paypal	PayPal
Lodged Card	Saved Agent Card
Invoice/Direct Debit	On Account

Payment Type Codes

Name	Description
INV	On Account
CARD	Credit or debit card
ELV	ELV or SEPA Direct Debit

Pricing & Optional Extra Types

Name	Type	Description
AD	Passenger	Adult
CH	Passenger	Child
IN	Passenger	Infant
VEH	Vehicle	Vehicle
BAS	Extra	Booster Seat (15 - 25kg, 33lb - 3st 13lb, 4 - 7yr)
BAS2	Extra	Booster Seat (22 - 36kg, 3st 7lb - 5st 9lb, 7 - 12yr)
BBX	Extra	Bike Box
BYOB1	Extra	BYO Booster Seat (15 - 25kg, 33lb - 3st 13lb, 4 - 7yr)
BYOB2	Extra	BYO Booster Seat (22 - 36kg, 3st 7lb - 5st 9lb, 7 - 12yr)
BYOCS	Extra	BYO Child Seat (9 - 18kg, 20 - 40lb, 9mths - 4yr)
CHS	Extra	Child Seat (9 - 18kg, 20 - 40lb, 9mths - 4yr)
CWC	Extra	Wheelchair (foldable)
EXS	Extra	Extra Suitcase
GCS	Extra	Golf Clubs
PUC	Extra	Pushchair
SCO	Extra	Mobility Scooter
SKE	Extra	Ski Equipment
SUE	Extra	Surf Equipment
WC	Extra	Extra 30 minutes Wait Time
WLF	Extra	Walking Frame