Dynamic API

Workflow

HotelsPro API (Coral) has 4 steps of flow. Please do not forget that all steps are must.

Coral Workflow

Destination Structure

In order to supply maximum level of destination hierarchy in human readable format (national, regional, sub-regional, local and sub-destination based), Platform 2 provides multi-level destination structure by parent-child relation with more-to-more connectivity.

Below chart shows structure sample of destination to sub-destination relation :

Subdestinations

Sub-destination’s parent destination code refers higher destination that covers sub destination.

More-to-more structure gives best application of destinations and creates destination matrix in order to provide ability to reach sophisticated certain destination that have complex relation with destination network.

Below chart shows destination structure of static database :

Destinations

A standard hotel booking progress starts with "search" action and the general flow continues as "search -> check availability -> provision -> booking" steps. During this flowing process, for each step, unique codes must be carried to the next step.

This method is used for getting hotel information and properties on a specific date range (check-out - check-in), with a designated amount of people (pax) from /search endpoint.

Example(1): GET /api/v2/search/?pax=3&checkout=2017-01-25&checkin=2017-01-20&hotel_code=10e6cc&client_nationality=tr&currency=EUR

Response:

{
  "count": 1,
  "code": "20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "10e6cc",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "206e4",
      "products": [
        {
          "code": "10e6cc_56305817968661_0_3_2_2_0_1_2406044196_0_3-0-0.20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "357.21",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 3
              },
              "room_category": "Standard",
              "room_description": "Triple Room",
              "nightly_prices": {
                "2017-01-20": "71.44",
                "2017-01-21": "71.44",
                "2017-01-22": "71.44",
                "2017-01-23": "71.44",
                "2017-01-24": "71.44"
              },
              "room_type": "TB"
            }
          ],
          "nonrefundable": null,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "view": false
        }
      ]
    }
  ]
}

Example(2): 
GET /api/v2/search/?pax=1&checkout=2017-01-25&checkin=2017-01-20&hotel_code=103752&client_nationality=us&currency=EUR&max_product=1

Response:

{
  "count": 1,
  "code": "20170120_5_1_1_232_462875c1706e462da59554d407e4774d_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "103752",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "206ec",
      "products": [
        {
          "code": "103752_58502674047670_2_2_2_2_0_1_238342530_0_0-0-0.20170120_5_1_1_232_462875c1706e462da59554d407e4774d_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "559.34",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 1
              },
              "room_category": "Standard",
              "room_description": "SINGLE STANDARD",
              "nightly_prices": {
                "2017-01-20": "111.87",
                "2017-01-21": "111.87",
                "2017-01-22": "111.87",
                "2017-01-23": "111.87",
                "2017-01-24": "111.87"
              },
              "room_type": "SB"
            }
          ],
          "nonrefundable": false,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "view": false
        }
      ]
    }
  ]
}

Example(3):

POST /api/v2/search/?pax=3&checkout=2017-01-25&checkin=2017-01-20&client_nationality=tr&currency=EUR

POST BODY: hotel_code=10e6cc, ...

Note : You can pass 500 hotel code in body

Response:

{
  "count": 197 ,
  "code": "20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "10e6cc",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "206e4",
      "products": [
        {
          "code": "10e6cc_56305817968661_0_3_2_2_0_1_2406044196_0_3-0-0.20170120_5_3_1_224_9fa211e8a14f44e5ae684bf4ee4b59f2_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "357.21",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 3
              },
              "room_category": "Standard",
              "room_description": "Triple Room",
              "nightly_prices": {
                "2017-01-20": "71.44",
                "2017-01-21": "71.44",
                "2017-01-22": "71.44",
                "2017-01-23": "71.44",
                "2017-01-24": "71.44"
              },
              "room_type": "TB"
            }
          ],
          "nonrefundable": null,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "view": false
        }
      ]
    }

  ...

  ]
}

Request Base Parameters

Name Value Required Description
format string no Type of the data to be received as a response. JSON is currently supported. Default setting is human readable structured plain html. The default is determined by Accept header of the HTTP Request.
pax custom-list yes Indicates amount of persons. 
A few input examples are as follows : pax = 4 (4 adults) pax = 2,12,11 (2 adults, 2 children with ages of 12 and 11) First integer is the number of adults, 
and the rest after the first comma will be taken as list of children ages.
 Can be used multiple times in one search separated with &.
checkout dateobject yes Indicates check-out date. Can not be greater than check-in. The range between check-in and checkout is limited to maximum 30 days. Must be in the formatted as YYYY-MM-DD
checkin dateobject yes Indicates check-in date. Can not be greater than checkout. The range between checkin and checkout is limited to maximum 30 days. Must be in the formatted as YYYY-MM-DD
currency string sometimes Indicates requested currency of the product prices. Must be one of the Consumer's account currencies. This field is required if multiple currencies are enabled on the Consumer's account.
client_nationality string yes Indicates two letter country code of the client nationality. The nationality must refer to a valid country_code within countries table.
max_product integer optional Indicates maximum amount of products per hotel returned from the API. If not set, no limit set to product count. default is no limit.

Restrictions:

Primary Search Methods

There is a primary method available to limit the selection of hotels returned in the request, presented below in no particular order.
 The method allows an explicit set of products to be returned via a specific hotel_code. Only this method can be used at a time.

Using Multiple hotel_code(s)

A hotel code or list of hotel codes with comma separation (see: example below) can be used with this method. Hotel codes from different destinations can be used. It is possible to send multiple hotel code search request at the same time.

Name Value Required Description Restrictions
hotel_code string Yes* The unique code(s) for a hotel. Maximum 5000 hotel in one request allowed.

(*) : Required only for this search method

Multiple Hotel Codes Search Examples

Below search beginning with 14097 hotel code (Didi Hotel/Turkey) returns rooms from Didi Hotel :

GET /api/v2/search/?hotel_code=14097e

Below search beginning with 14097 hotel code (Didi Hotel/Turkey) and 15325f hotel code (Olive Grove Resort / Greece) returns rooms from Didi Hotel and Olive Grove Resort even they are hotel codes from different destinations.

GET /api/v2/search/?hotel_code=14097e,15325f

Using destination_code

This method can be used to get hotel list on a specific destination such as London.

Name Value Required Description
destination_code string Yes* The unique code for the destination.

(*) : Required only for this search method

Destination search example

Below search beginning with 11260 destination code (London/England) returns hotel list at London :

GET /api/v2/search/?destination_code=11260

Using Geo-Location

Geo-Code is geographic coordinating system which points the location on the map by latitude and longitude. This method can be used to get hotel list on a specific circle area.

Geo Search

Latitude, longitude and radius information can be used with this method.

Note that, one geo search query will return 200 hotels at maximum even if there are more hotels available at that radius.

Name Value Required Description Restrictions
lat string Yes* latitude(φ) geographic coordinate that specifies the north-south position of a point on the Earth's surface. This value must be between -90 and 90
lon string Yes* Longitude, geographic coordinate that specifies the east-west position of a point on the Earth's surface. This value must be between -180 and 180.
radius string Yes* Distance from given point. (in meter) This value is maximum 20000(20km).

(*) : Required only for this search method

Geo Codes Search Example

Search hotels around 1km radius from Eifel Tower:

Eifel Tower

GET /api/v2/search/?pax=1&checkout=2017-01-25&checkin=2017-01-20&lat=48.858543&lon=2.294502&radius=1000&client_nationality=gb&currency=GBP

Example response for the above geo-search request is below :

Example Response

{
  "count": 19,
  "code": "20170120_5_1_3_76_f9ef5a5a78734d44a835e07eb99d4650_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "106f18",
      "checkout": "2017-01-25",
      "checkin": "2017-01-20",
      "destination_code": "20a11",
      "products": [
        {
          "code": "106f18_55217158285494_1_2_2_2_0_3_238342530_0_0-0-0.20170120_5_1_3_76_f9ef5a5a78734d44a835e07eb99d4650_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "281.94",
          "currency": "GBP",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 1
              },
              "room_category": "Standard",
              "room_description": "SINGLE STANDARD",
              "nightly_prices": {
                "2017-01-20": "56.39",
                "2017-01-21": "56.39",
                "2017-01-22": "56.39",
                "2017-01-23": "56.39",
                "2017-01-24": "56.39"
              },
              "room_type": "SB"
            }
          ],
          "nonrefundable": true,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "view": false
        }
      ]
    },
    ...
  ]
}

Response Object Parameters

Name Value Description
checkin string Check-in date. Format : YYYY-MM-DD
checkout string Check-out date. Format : YYYY-MM-DD
destination_code string The code resembles that is the equivalent
of the searched hotel destination. The unique code refers to destination_code within destinations table.
hotel_code string The unique code for the hotel.
products list List of products and details
code string Product code of returned product
currency string Currency code of returned product
meal_type string Meal type code of returned product
nonrefundable boolean Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products. After 2016-12-01, this flag will not return NULL.
pay_at_hotel boolean Information of the payment either the customer can pay at the time of arrival to the hotel itself or not. If this parameter is false than hotel_currency and hotel_price will be returned as null
hotel_currency string Currency of the hotel_price. Only returned in case if pay_at_hotel variable is true.
hotel_price decimal The price in hotel currency that the customer will pay at the time of arrival to the hotel itself. Only returned in case if pay_at_hotel variable is true.
price decimal Product price value in currency determined in search query.
minimum_selling_price decimal It is the minimum selling price to the end consumer. In other words, a price that can't in any circumstances be undersold.
rooms list List of returned rooms. For detailed information and example about room(s) list of the product please see section "Contents of Rooms List"
view boolean Information about if the room has a view.
supports_cancellation boolean Indicates the product whether can cancel or not over api
policies list List of cancellation policies. For detailed information and example about policies list of the product, please see section "Contents of Policies List"
next_page_code string This parameter is DEPRECATED, so returns null.
max_wait string Your maximum wait configuration(SLA Time).
response_time string Response time
Contents of Policies List
Name Value Description
days_remaining decimal Number(s) of remaining days to check-in date. days_remaining = today - checkin
ratio decimal Ratio of cancellation charge. The multiplier that will be applied to price to calculate cancellation charge.
Example Policies Response
"policies": [
        {
            "days_remaining": 1,
            "ratio" : "0.45"
        },
        {
            "days_remaining": 7,
            "ratio": "0.01"
        }
     ],
Contents of Room List
Name Value Description
pax dict A dict consists of adult quantity, children ages keys.
adult_quantity int Total number of adults
children_ages list A list consisting of integers which represent children guest ages
room_category string Represents the category of the room referring to room categories table.
room_descriptions string Description of the room
nightly_prices dict List of prices to pay for each night of the room. Dictionary contains night date and price pairs day by day. Date format is "yyyy-mm-dd"
room_type string Represents the type of the room
Important Notice

search/availability/hotel-availability/provision/book endpoints return the rooms data in the same template above.

Example Room List Response

Below example shows a multi pax search request & response for 1 adult and 2 adults 2017-01-21 to 2017-01-23.

GET /api/v2/search/?pax=1&pax=2&checkout=2017-01-23&checkin=2017-01-21&destination_code=19064&client_nationality=GB&currency=EUR

{
  "count": 52,
  "code": "20170121_2_1~2_1_76_b583b11744d54725b438fdecc3f8c066_",
  "next_page_code": null,
  "max_wait": "1.0",
  "response_time": "0.96",
  "results": [
    {
      "hotel_code": "100ff3",
      "checkout": "2017-01-23",
      "checkin": "2017-01-21",
      "destination_code": "19064",
      "products": [
        {
          "code": "100ff3_242336389998_2_2_2_2_0_1_1483860825_0_0-0-0~1-0-0.20170121_2_1~2_1_76_b583b11744d54725b438fdecc3f8c066_",
          "offer": false,
          "pay_at_hotel": false,
          "price": "84.07",
          "currency": "EUR",
          "rooms": [
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 1
              },
              "room_category": "Standard",
              "room_description": "SINGLE STANDARD",
              "nightly_prices": {
                "2017-01-21": "18.68",
                "2017-01-22": "18.68"
              },
              "room_type": "SB"
            },
            {
              "pax": {
                "children_ages": [],
                "adult_quantity": 2
              },
              "room_category": "Standard",
              "room_description": "DOUBLE STANDARD",
              "nightly_prices": {
                "2017-01-21": "23.35",
                "2017-01-22": "23.35"
              },
              "room_type": "DB"
            }
          ],
          "nonrefundable": false,
          "supports_cancellation": true,
          "hotel_currency": null,
          "hotel_price": null,
          "meal_type": "RO",
          "minimum_selling_price": null,
          "view": false
        }
      ]
    },
    ...
  ]
}

Check Hotel Availability

This method is used for getting information of a hotel availability via GET from /hotel-availability endpoint. Check Hotel Availability can be used multiple times to check the availability of the hotel in time range. It is advised to post the request in every display of hotel - detail or hotel - list functionalities in order to avoid availability or price changes and keeping pricing information up-to-date.

This endpoint returns a list of availability endpoint response. /availability endpoint returns up-to-date availability information for a single room; /hotel-availability endpoint returns up-to-date availability information for all rooms of a single hotel.

! If you want to get all up-to-date availability information for a single hotel's rooms then you should use this endpoint instead of /availability request for each room.

Note that: Hotel availability response is valid for 45 minutes. When you get an hotel availability response you have 45 minutes to go to book step. If you have missed this time and you have to get hotel-availability response again for that hotel.

Timeout duration: Hotel availability request may take 90 seconds, so client should wait for response.

Request Base Parameters

Name Value Required Description
search_code string yes This is the code from the response of the search request. (code)
hotel_code string yes This is the code from the response of the search request. (hotel_code)

GET /api/v2/hotel-availability/?<search_code>&<hotel_code>

Example Response

GET /api/v2/hotel-availability/?search_code=20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_&hotel_code=135f3a

{
  "code": "20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_",
  "count": 25,
  "results": [
    {
      "code": "135f3a_55186709030717_1_2_2_2_0_1_438178821_23_0-1-0.20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_",
      "destination_code": "206ec",
      "hotel_code": "135f3a",
      "additional_info": "",
      "checkin": "2017-01-20",
      "checkout": "2017-01-25",
      "price": "212.38",
      "currency": "EUR",
      "pay_at_hotel": false,
      "hotel_price": null,
      "hotel_currency": null,
      "meal_type": "RO",
      "nonrefundable": true,
      "view": false,
      "rooms": [
        {
          "pax": {
            "children_ages": [],
            "adult_quantity": 1
          },
          "room_category": "Shared Facility",
          "room_description": "TWIN WITH SHARED BATHROOM",
          "nightly_prices": {
            "2017-01-20": "42.47",
            "2017-01-21": "42.47",
            "2017-01-22": "42.47",
            "2017-01-23": "42.47",
            "2017-01-24": "42.47"
          },
          "room_type": "SB"
        }
      ],
      "supports_cancellation": true,
      "minimum_selling_price": null,
      "offer": false,
      "policies": [
        {
          "ratio": "1.00",
          "days_remaining": 44
        }
      ]
    },
    ...
  ]
}

Response Object Parameters

Name Value Description
product_code string Product code of returned product.
destination_code string The unique code for the destination.
hotel_code string The unique code for the hotel.
additional_info string Additional information about the room including specific information about product restrictions, rules, warnings etc.
checkin string Check-in date. Format : YYYY-MM-DD
checkout string Check-out date. Format : YYYY-MM-DD
price decimal The amount that will be charged for this booking (*)
currency string Indicates currency of the price. It is optional to send a specific currency option to receive the response price in specific currency. (EUR , USD , GBP etc.). The currency must refer to a valid currency_code within currencies table.
pay_at_hotel boolean Information of the payment either the customer can pay at the time of arrival to the hotel itself or not
hotel_price decimal The local price value.
hotel_currency string Indicates the currency of hotel_price. It’s similar type of currency variable.
meal_type string Meal type code of returned product.
supports_cancellation boolean Indicates the product whether can cancel or not over api.
nonrefundable boolean Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products. After 2016-12-01, this flag will not return NULL.
view boolean Information about if the room has a view.
rooms list List of returned rooms. For detailed information and example about room(s) list of the product please see section "Contents of Rooms List"
pax dict A dict consists of adult quantity, children ages keys.
adult_quantity int Total number of adults
children_ages list A list consisting of integers which represent children guest ages
room_category string Represents the category of the room referring to room categories table.
room_description string Description of the room
room_type string Represents the type of the room
supports_cancellation boolean Indicates the product whether can cancel or not over api.
minimum_selling_price decimal It is the minimum selling price to the end
offer boolean
policies list List of cancellation policies. For detailed information and example about policies list of the product, please see section “Contents of Policies List”
days_remaining int Number(s) of remaining days to check-in date. days_remaining = today – checkin_date
ratio decimal The multiplier that will be applied to price to calculate cancellation charge.
providers list
list_price decimal
cost decimal

Provision

This method is used to get the last second information of the product that either it is available or not by POST method. If the product is available, this method returns with provision code. Provision method should be used just before booking to make sure the price and room is still available after the last executed search request. Carrying the code came from 'products' list in response of the search request is mandatory to execute provision command. It is not possible to make booking without posting provision code. So, this method is mandatory to make booking. Also timeout between provision and booking process can occur after 60 seconds.

Timeout duration: Provision request may take 90 seconds, so client should wait for response.

Request Base Parameters

Name Value Required Description
code string yes* This is the code from the response of the search request. (product code)

Example Response

POST /api/v2/provision/<code>

Example Response

POST /api/v2/provision/135f3a_55186709030717_1_2_2_2_0_1_438178821_23_0-1-0.20170120_5_1_1_76_9fc721a769b9430a8ed6855740d25234_

{
  "code": "PL77K57A2CLA",
  "destination_code": "206ec",
  "offer": false,
  "price": "212.38",
  "currency": "EUR",
  "rooms": [
    {
      "pax": {
        "children_ages": [],
        "adult_quantity": 1
      },
      "room_category": "Shared Facility",
      "room_description": "TWIN WITH SHARED BATHROOM",
      "nightly_prices": {
        "2017-01-20": "42.47",
        "2017-01-21": "42.47",
        "2017-01-22": "42.47",
        "2017-01-23": "42.47",
        "2017-01-24": "42.47"
      },
      "room_type": "SB"
    }
  ],
  "nonrefundable": false,
  "additional_info": "Check-in hour 15:00 – 02:00. No alcohol is served. Deposit on arrival   . Early departure. Twin beds are bunk beds. Children under 0-17 years old are not permitted to stay in a bed room type.",
  "supports_cancellation": true,
  "hotel_code": "135f3a",
  "hotel_currency": null,
  "hotel_price": null,
  "checkin": "2017-01-20",
  "meal_type": "RO",
  "policies": [
    {
      "ratio": "1.00",
      "days_remaining": 44
    }
  ],
  "view": false,
  "checkout": "2017-01-25",
  "minimum_selling_price": null,
  "pay_at_hotel": false
}

Response Object Parameters

Name Value Description
code string The provision code. This code is necessary to go to booking stage.
destination_code string The unique code for the destination
offer boolean
price list The amount that will be charged for this booking.
currency string Indicates currency of the price. It is optional to send a specific currency option to receive the response price in specific currency. (EUR , USD , GBP etc.). The currency must refer to a valid currency code within currencies table.
cost decimal
rooms list List of returned rooms. For detailed information and example about room(s) list of the product please see section "Contents of Rooms List"
pax dict A dict consists of adult quantity, children ages keys.
adult_quantity int Total number of adults
children_ages list A list consisting of integers which represent children guest ages
room_category string Represents the category of the room referring to room categories table.
room_description string Description of the room
room_type string Represents the type of the room
nonrefundable boolean Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products. After 2016-12-01, this flag will not return NULL.
list_price decimal
supports_cancellation boolean Indicates the product whether can cancel or not over api.
additional_info string Additional information about the room including specific information about product restrictions, rules, warnings etc.
providers list
hotel_code string The unique code for the hotel.
hotel_currency string Indicates the currency of hotel_price. It’s similar type of currency variable.
hotel_price decimal The local price value.
checkin string Check-in date. Format : YYYY-MM-DD
meal_type string Meal type code of returned product.
policies decimal List of cancellation policies. For detailed information and example about policies list of the product, please see section “Contents of Policies List”
days_remaining int Number(s) of remaining days to check-in date.
ratio decimal The multiplier that will be applied to price to calculate cancellation charge.
view boolean Information about if the room has a view.
checkout string Check-out date. Format : YYYY-MM-DD
minimum_selling_price decimal It is the minimum selling price to the end
pay_at_hotel boolean Information of the payment either the customer can pay at the time of arrival to the hotel itself or not

Booking

This method is the fourth and last step of hotel booking. The method is used to book a product that have made sure available with 'Provision' request. Carry the unique code which has got from Provision response. And also guest information and payment information is used to get. At the end of this method if provision code is not expired and property information is still valid, booking process will be completed.

Timeout duration: Booking request may take 90 seconds, so client should wait for response.

Request Base Parameters

Name Value Required Description Restrictions
card_cvc string Conditional* Credit card cvc value 3 or 4 digits
card_expiration string Conditional* Credit card expiration date YYYY-MM format
card_holder_name string Conditional* Credit card holder name
card_number string Conditional* Credit card number Must be valid card number
card_type string Conditional* Credit card type Visa / MasterCard
code string yes Product code that have been retrieved from provision response
email string Conditional* Guest email address Must be valid email address
format string no Type of the data document that is going to be received as a response. Only JSON is currently supported
name string yes Must be name=1,firstname,lastname,type format (1 refers room number, type can be adult/child) 200 Characters, max.
phone_number string Conditional* Guest phone number. Phone Numbers must be at least 5 digits long and have at least one different digit (ex:5555555555 is not valid)
special_request string no A free text section where the personal making the hotel reservation can make special requests. 255 Characters, max.

(*) : Conditional : Required for pay_at_hotel payment type.

Example Request Post

POST /api/v2/book/<code>

Request Body

pay_at_hotel type

name&card_cvc&card_expiration&card_holder_name&card_number&card_type&email&phone_number

prepaid

name

Response Objects

Example response for the above booking request is below:

Example Response

POST /api/v2/book/PL77K57A2CLA

{
  "code": "B3CJBKKDU43F",
  "created_at": "2016-12-09 07:03:03.367699+00:00",
  "checkin": "2017-01-20",
  "checkout": "2017-01-25",
  "hotel_code": "135f3a",
  "destination_code": "206ec",
  "client_nationality": "gb",
  "pay_at_hotel": false,
  "currency": "EUR",
  "mealtype_code": "RO",
  "nonrefundable": false,
  "view": false,
  "policies": [
    {
      "days_remaining": 44,
      "ratio": "1.00"
    }
  ],
  "price": "212.38",
  "rooms": [
    {
      "pax": {
        "children_ages": "",
        "adult_quantity": 1
      },
      "room_category": "Shared Facility",
      "room_description": "TWIN WITH SHARED BATHROOM",
      "nightly_prices": {
        "2017-01-20": "42.47",
        "2017-01-21": "42.47",
        "2017-01-22": "42.47",
        "2017-01-23": "42.47",
        "2017-01-24": "42.47"
      },
      "room_type": "SB"
    }
  ],
  "status": "succeeded",
  "confirmation_numbers": [
    {
      "confirmation_number": "164-3015081",
      "names": [
        "John Doe"
      ],
      "rooms": [
        {
          "room_description": "TWIN WITH SHARED BATHROOM",
          "room_type": "TWN"
        }
      ]
    }
  ],
  "hotel_payment_info": [
    {
      "hotel_currency": null,
      "hotel_price": null
    }
  ],
  "minimum_selling_price": null,
  "special_request": null
}

Response Object Parameters

Name Value Description
code string booking code
created_at string Time of the booking
checkin dateobject Indicates check-in date
checkout dateobject Indicates check-out date
pay_at_hotel boolean Information of the payment either the customer can pay at the time of arrival to the hotel itself or not
price decimal Total price of the booking
currency string Currency code
client_nationality string Indicates two letter country code of the client nationality
destination_code string The unique code for the destination
hotel_code string The unique code for the hotel
mealtype_code string The unique code for the meal type
policies list Policies list including days_remaining and ratio
nonrefundable boolean Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products. After 2016-12-01, this flag will not return NULL.
view boolean Information about if the room has a view.
supports_cancellation boolean Indicates the product whether can cancel or not over api
status string Status of the booking Possible status list; 'Succeeded', 'Failed', 'Cancelled'
confirmation_numbers list A list dictionaires that has the number of the booking. The names that the booking has been done under and the partner of it.
minimum_selling_price decimal It is the minimum selling price to the end
special_request string Given free format text to inform hotel (remember that, it could be unsent)

Unsaved Condition Recovery

When you send a book request and receive no response due to network problems (timeout issues, losing connection, etc.), you need to use the /api/v2/bookings/<code> endpoint to double-check the booking result and ensure if the book request is confirmed/completed or not.

Cancellation

This method is used to cancel booking. Code value from the booking response must be included.

Booking code should be included which has been received from booking process.

Request Base Parameters

Name Value Required Description
code string yes The code from response of the booking request. (code)

Example Response

POST /api/v2/cancel/<code>

{
  "currency": "EUR",
  "charge_amount": "212.38",
  "code": "B3CJBKKDU43F"
}

Response Object Parameters

Name Value Description
currency string currency type of the charge_amount
code string cancellation code
charge_amount decimal The amount of penalty payment for cancelling the booking. No charge is taken if returned null.

Bookings

This method is also known for 'booking list' and it is for retrieving past booking data.

It has three uses. If you are authorized with a specific consumer, it will get you all the booking data related to that consumer.

Second use is that you can do a request with a specific booking code (or provision code) to retrieve that specific booking data.

And finally, as it is stated in the "Unsaved Condition Recovery" section, this method should be used to ensure book request status in case of not having a proper booking response.

Request Base Parameters

GET /api/v2/bookings/<code>

Name Value Required Type Description
code string No - This is the code that taken from the response of the bookings request. (Or provision code can be used to make a booking request.)
from_date string No Query string This is the booking date for filtering the bookings from the from_date(YYYY-MM-DD).
to_date string No Query string This is the booking date for filtering the bookings until the to_date(YYYY-MM-DD).
format string No Query string Only JSON supported

If code, from_date and to_date parameteres are not provided, the result will include the bookings of that day only.

Example Response

GET /api/v2/bookings/B3CJBKKDU43F

{
  "code": "B3CJBKKDU43F",
  "created_at": "2016-12-09T07:03:03.367Z",
  "checkin": "2017-01-20",
  "checkout": "2017-01-25",
  "hotel_code": "135f3a",
  "destination_code": "206ec",
  "client_nationality": "gb",
  "pay_at_hotel": false,
  "currency": "EUR",
  "mealtype_code": "RO",
  "nonrefundable": false,
  "view": false,
  "policies": [
    {
      "days_remaining": 44,
      "ratio": "1.00"
    }
  ],
  "price": "212.38",
  "rooms": [
    {
      "pax": {
        "children_ages": "",
        "adult_quantity": 1
      },
      "room_category": "Shared Facility",
      "room_description": "TWIN WITH SHARED BATHROOM",
      "nightly_prices": {
        "2017-01-20": "42.47",
        "2017-01-21": "42.47",
        "2017-01-22": "42.47",
        "2017-01-23": "42.47",
        "2017-01-24": "42.47"
      },
      "room_type": "SB"
    }
  ],
  "status": "cancelled",
  "confirmation_numbers": [
    {
      "confirmation_number": "164-3015081",
      "names": [
        "John Doe"
      ],
      "rooms": [
        {
          "room_description": "TWIN WITH SHARED BATHROOM",
          "room_type": "TWN"
        }
      ]
    }
  ],
  "hotel_payment_info": [
    {
      "hotel_currency": null,
      "hotel_price": null
    }
  ],
  "minimum_selling_price": null,
  "special_request": null
}
Name Value Description
code string booking code
created_at string Time of the booking
checkin dateobject Indicates check-in date
checkout dateobject Indicates check-out date
pay_at_hotel boolean Information of the payment either the customer can pay at the time of arrival to the hotel itself or not
price decimal Total price of the booking
currency string Currency code
client_nationality string Indicates two letter country code of the client nationality
destination_code string The unique code for the destination
hotel_code string The unique code for the hotel
mealtype_code string The unique code for the meal type
policies list Policies list including days_remaining and ratio
nonrefundable boolean Flag that determines whether the product can be refunded when cancelled. Some providers are returning us NULL for nonrefundable flag. You may receive NULL for some products. After 2016-12-01, this flag will not return NULL.
view boolean Information about if the room has a view.
supports_cancellation boolean Indicates the product whether can cancel or not over api
status string Status of the booking Possible status list; 'Succeeded', 'Failed', 'Cancelled'
confirmation_numbers list A list dictionaires that has the number of the booking. The names that the booking has been done under and the partner of it.
minimum_selling_price decimal It is the minimum selling price to the end
special_request string Given free format text to inform hotel (remember that, it could be unsent)

Errors, Error Codes

Errors and error codes are generated specific messages corresponds to the information. When an error occurs, API sends a response which contains error_code and detail information. detail field can be string or javascript object.

{
 "error_code": 4405,
 "detail": "Method not allowed"
}
{
 "error_code": 4400,
 "detail": {
 "card_type": ["'diners' is not a valid card type. Supported cards: visa"],
 "card_number": ["Card number is not valid"]
 }
}

Error Code List

http_status error_code error_type detail detail parameter
400 4400
common error
Invalid client IP client_IP
Invalid channel channel
booking error
Passenger names are required name
Search pax info and book pax info does not match detail
This card type is not valid, please check. Available cards:... card_type
Card number is not valid card_number
At least one name parameter is required name
Credit card info is required for direct payment hotels detail
cancellation error Booking cannot be cancelled after checkin date detail
search error
Invalid currency detail
Invalid destination code destination_code
Checkin date is invalid checkin
Checkin date is in the past checkin
Checkout date is invalid checkout
Checkout date appears to be earlier than the checkin date non_field_errors
Number of room cannot be more than 5 pax
Number of adults per room must be between 1-6 pax
Number of children per room cannot be more than 4 pax
Number of passengers per room cannot be more than 6 pax
Number of night for a stay cannot be more than 30 days non_field_errors
Destination code is required non_field_errors
Invalid destination code destination_code
401 4401 common error
Authentication credentials were not provided.
Invalid username/password
Channel is disabled
404 4404 booking error
Please go to provision step first! detail
Search result with given code could not be found detail
Please go to provision step first detail
cancellation error Booking not found detail
availability/provision error Product is expired detail
405 4405 common error Method not allowed detail
409 4409 booking error
This product is already purchased detail
We could not process the booking due to an unknown error
cancellation error Booking already cancelled detail
410 4410 booking error The room is no longer available detail
500 5500 common error There was an error. Please try again later