General info

The following information is true for every type of request

  • All dates are in "dd-mm-yyyy" format. Example: 15 March 2016 -> "15-03-2016".
  • All country codes are 2 character ISO 3166-1-alpha-2 codes. More details here.
  • All request must use HTTP compression. More details here.
  • All requests are authenticated using header parameters ('UserName' and 'AccessToken'). You'll find more informations below.
  • Your development/production machines must have the correct date and time set, in order to successfully authenticate.
  • You can use SecretKey - "Demo", UserName - "Demo" to authenticate each request type from our sandbox (valid only in demo mode).

Authentication algorithm

You will receive a private key from us that will be used for authentication. To make the key stronger we will use a salt that will be total minutes elapsed since 1 Jan 1970 00:00, also known as Unix time (note that use minutes and not seconds).

We are concatenating our secret key, for example "DarthVader", with total minutes elapsed from 1970 until now, 24272143 as I'm writing this and we get "DarthVader24272143".

Now that we have our salted key we will encript it using SHA-1 algorithm, and this will render a hexadecimal number, 40 digits long. For our little example the result will be "f595d10fa50123c3a82c85f538d7d72092907bfa". This will be your acces token to be placed in every request's header along with your username.

For this to work your machine must have the correct date and time set, otherwise you'll get another salt for your secret key, resulting in a different access token. We know that time synchronization on servers can be harsh so we will tolerate a +/-5 minutes difference, but not more. Pretty simple, huh?

Static Data

Hotel details like description, pictures, address etc rarely change, that's why it is ok to download static data once, update it from time to time and use those hotel details in your website. This way we will not send these on our Booking Flow API, allowing us to have a light and fast Booking Flow API.

Please take a look at our sandbox for static data following the link below. From there you can make requests to our demo api and you'll also find the documentation about the request and response parameters.

The flow for downloading static data is simple and intuitive.

  • First you can get all the country codes using Get country method.
  • Then for each country code previously downloaded, you can get all the hotel codes from that country using Get hotel codes by country code method. Please note that this method has an optional parameter named "updatedAfter". On initial population, you should leave it empty so you'll get all our hotels. After initial population you can start using the field and put there the last date of your request, this way you'll get only the hotels that were modified after that date (inclussive).
  • For each hotel code received, you can get the complete hotel details for it using the method Get hotel details by code .
  • Beside the hotel data you should download also our Destination list. You will use this on our Booking Flow API search requests when making reservations. To download the destination list use the method Get destinations . You should download the destinations each and every time you perform a static data update in order to get additional destinations that might be added lateron.
  • Our general recommendation for how often to download our static data is twice per month. If you expect to receive heavy traffic on your website then you should consider to update once per week or even more frequently. While for new websites or the ones with very low traffic it can be once per month.

Booking Flow

The minimum recomended steps to create a reservation are: Get Hotel Availability -> Check Rates -> Book

Our REST API provides you the ability to choose between xml and json request/response. We have full integration support for multiple programming languages providing you with already created API clients in order to have a smooth integration process. In order to minimise the scenarios where the price and availability change during the booking flow all the requests are made directly at the suppliers therefore our booking flow is live one.

Please take a look at our booking flow sandbox following the link below. From there you can make requests to our demo api and you'll also find the documentation describing all the parameters. Note that some parameters from our request example must be modified with real values obtained from previous request. For example on a CheckRates request you should replace the RoomGroup elements with real values obtained from HotelAvailability request.

Here is how a 3 steps booking should be created:

  • First we get available hotels that satifies our search criteria (occupancy, check in, check out) using Get Hotel Availability method. In the response for this method we get a list of hotels that contains a list of RoomGroup. A RoomGroup is an exact viable option for booking, a combination of rooms that satisfies your search criteria. This means we already combined rooms received from the providers in order to give you the posibillity to immediatly book a RoomGroup. All these actually mean less work on your side.
  • Like we mentioned before, hotel availability and prices often change. Between a search and a book sometimes can be more than 20 minutes. In all this time your selected room can become sold out or have its price modified. To prevent this and always have latest availability and prices for your room we strongly recommend that before making the reservation to reckeck prices and availability using Check Rates method. Just get the RoomGroup info that you want to book, put them in the CheckHotelRatesRQ and have your price and availability rechecked. Also you can use this method to get Cancellation Policies for your selected rooms.
  • Now that we have our price and availability rechecked, we can book our room(s) using Book method. Take in consideration that even in the time between Check Rates and Book request, availability and prices can stil change, but this seldomly occur. In case that availability changes (room sold out) your reservation will fail. In case that price changes you can get a reservation with a bigger or lower price or can fail with a price changed error. This behaviour depends by provider. Some of them give us the posibility to send requested price in the book request, so if the price changes the book will fail, while others don't have such a feature so we can get a reservation with different price than the requested one. Note that booking process is like a transaction, if one of your reservation from the RoomGroup fails, all will fail.

After a booking is confirmed you have the posibillity to cancel it or to retrieve its details

  • Cancel it using Cancel Reservation method. Just send us the reservation id and we will cancel it. The reservation price will be updated to the cancellation penalty fee, or with 0 if such a penalty doesn't exist.
  • Retrieve your reservation details using Get Reservation method. Just give us a reservation id and we will give you all reservations made together with this reservation. Useful to get live details about your bookings, like booking status and prices.