Hotel API

General

What are the basic steps involved in integrating Cleartrip's Hotel API for distribution?
The following are the activities to be executed:

  • Contact Cleartrip's business development team, Sandeep Sanil (sandeep.sanil@cleartrip.com) of the intent to integrate APIs along with your company information.

  • Register on the Cleartrip staging environment (http://apistaging.cleartrip.com).
  • Send a mail to api.support@cleartrip.com for username and password to access API documentation.
  • Email the user-id to api.support@cleartrip.com. An API key and the Cleartrip staging API URLs will be emailed.
  • Obtain the API documentation and the URLs for the API staging environment.
  • Design and code the search/book/cancel flows, using the documentation provided.
  • Provide URLs and authentication to the test environment, so that cleartrip can test and validate the site.
  • Upon validation, register on the cleartrip production environment (http://www.cleartrip.com/register)
  • Email the user-id to api.support@cleartrip.com. An API key and the cleartrip production API URLs will be provided.
What payment options are available in the Cleartrip API?
The APIs allow the payment by Credit Card and Deposit Account.
What type of credit cards are allowed?
The following cards can be used to purchase the inventory using the Cleartrip API:
  • MasterCard issued in India
  • Visa issued in India
  • Amex cards issued in India
  • Citibank Diners Club cards issued in India
Does the integrator or the integrator's customer have to pay any payment gateway fees for the credit card usage?
No. Please check with api.support@cleartrip.com before integration.
How do we use the deposit account?

A deposit account ID is made available upon expressing intent to use the deposit account payment option.

You will have to make a cheque payment to Cleartrip (contact sandeep.sanil@cleartrip.com for details) against your deposit account.

You are allowed to transact on the deposit account, 24 hours after the money has been credited to Cleartrip's account.

How will refunds be managed, if the payment is made using credit cards?
All refunds will be credited back to the credit card. The time duration for refunds is 5 working days from the time that fulfillment confirms cancellation to the customer.
How will refunds be managed, if the payment is made using deposit account?
All refunds will be credited back to the deposit account. The time duration for refunds is 24 hours from the time that fulfillment confirms cancellation to the customer.
How can we track the trips that have been booked using the Cleartrip API?

Cleartrip provides a dashboard for this purpose. You can view the trips, trip details, deposit account details etc using the dashboard. The dashboard is provided, when you login into your account on Cleartrip.

You can search for trips based on customer details and trip-references to help service your customer.

You can also create and download standard MIS reports of your transactions from the dashboard.

Technical

What is the support turnaround time?

If you are in the integration phase, you can expect an email/resolution within 24 hours.

If you are in production phase, you can expect an email/resolution within 4 hours.

What is the general process flow for API usage?
  1. Make a search call with the parameters as specified in the API documentation.
  2. Make a rate rules call with the information obtained from the response of the search call.
  3. A book call is then made with the information obtained from the response of the search call.
  4. A cancel call can be made as per the rules within the API documentation.
Where can we find the list of input cities?

The list of input cities can be found at http://www.cleartrip.com/places/hotels/city_list.txt

Where can we find the list of hotels that are available on the Cleartrip API?

You can find the list of hotels at http://www.cleartrip.com/places/hotels/hotel_directory.txt

Based on the hotel-ids found in the hotel directory, you can use the hotel-info API to download the detailed information about each hotel as specified in the API documentation.

We have a property list of our own and we would like to match those with the properties available on the Cleartrip API. Where can we find more information on hotel properties?
http://www.cleartrip.com/places/hotels/hotel_matches.txt provides a list of hotels available on Cleartrip with basic information about each property and this can used for matching against your own property lists.
Who owns the hotel information? Do we need to show the credits?

The copyright information for each of the hotels is available in the hotel xml.

Note: If you are using this information, you will need to credit the copyright owners.

Can we download the hotel images in one package?

No. The volume makes it impractical. You can display the images of Cleartrip's website and you need to link these on your own.

The image links are available in the hotel-info xml and needs to be prefixed by the following links, depending on the Cleartrip environment that you are using:

Why are we unable to access the staging URL for a search call?

Please check the following:

  1. Basic authentication: Cleartrip staging environment is protected by basic authentication. You will need to ensure that your API calls are using the authentication. There is an example of how to do this in Java/Ruby in the API doc code samples.
  2. The URL has to be encoded.
  3. API Key – The API key (for the appropriate environment) is sent as part of the HTTP header. Refer to the API documentation code samples.
  4. URLs – These are the requests being sent to the correct URLs. Note the following URLs:

    for staging -

    for production -

Why are we getting fewer results returned in the API than what we get on the Cleartrip site (http://spi.staging.cleartrip.com Or http://www.cleartrip.com) for the same search parameters?

Cleartrip aggregates inventory from various suppliers. Cleartrip does not allow re-distribution of inventory from some suppliers. But, these are available for B2C customers on our site.

Further, our staging environment usually has fewer inventory than our production environment.

What do the pricing elements represent in the search response?

The <room-rates> element will contain one or more <room-rate> element.

Each of these <room-rate> elements correspond to a particular <room-type> and the pricing <rate-breakdown> is associated with that <room-type>.

Each of the <common-rate> elements within a <rate-breakdown> element represents pricing of that room-type on a per day basis irrespective of the number of rooms requested.

If two rooms were requested, the pricing within a given <common-rate> holds good for the day specified in the <date> element for both the rooms and if one room was requested, the pricing within the given <common-rate> holds good for the day specified in the <date> element for the one room that was requested.

How do we track transactions on the API system with our own key?

In the book call, pass in your transaction ID in the <affiliate-txn-id> element.

You can retrieve the itinerary details using the same transaction id.

How do we view all the trips that have been booked using the Cleartrip API system?

Log on to http://www.cleartrip.com with your registered user-id and password and access the “My account” link. This lists all the trips.

How do we retrieve information about a particular trip(booking)?

A booking-id is obtained as part of the book response. You can use the retrieve itinerary call with this booking-id to obtain details of a given trip.

For example: If “D0805080031” is obtained as the booking id, use http://apistaging.com/hotels/1.0/trips/D0805080031 or https://api.cleartrip.com/hotels/1.0/trips/D0805080031.

To retrieve the same details using your own transaction id, you can use http://apistaging.com/hotels/1.0/trips/ext/XXXXXXX or https://api.cleartrip.com/hotels/1.0/trips/ext/XXXXXXX, where XXXXXXX is your transaction id.

Why is the book call failing?

Check the following:

  • If the book URL is not accessible and if you cannot ping the environment, then contact your system administrator.

  • Basic authentication: Cleartrip staging environment is protected by basic authentication. You will need to ensure that your API calls are using the authentication. There is an example of how to do this in Java/Ruby in the API doc code samples.

  • API Key – The API key (for the appropriate environment) is sent as part of the HTTP header. Refer to the API doc code samples.

  • If the HTTP response code from the book call is a 400 series check,

    then check for parameters, and refer to the API documentation.

  • If the HTTP response code from the book call is a 500 series check,

    then check, whether the parameters gathered from a search response are obtained in the last 28 minutes.

Note: A room not being available is a Valid 500 response. It means that the room is no longer available.

If you have verified all of the above and the response XML along with the 500 series response that displays a “SYSTEM” error, then send the complete search response, book request and book response XMLs to api.support@cleartrip.com.

Note: All the three XMLs need to be attached in order, to get the support.

Why do some rates does not contain a TAX element?
The supplier of the rate has bundled the tax element into the base fare (BF) element and you should consider the TAX element to be Zero.
How often does the city list, hotel list, hotel information etc change?
These lists tend to change very often and are regenerated on a daily basis.
How do we get a "delta" of the changes to the above lists?
You can download the required lists from api.cleartrip.com/downloads
Why do HTTPS does not work for the book URL on staging?
HTTPS is not enabled on the API interface for staging. Please use https://apistaging.com/hotels/service/book
When I search for hotels in a particular city for a set of input parameters on the staging environment using the Cleartrip UI (http://apistaging.cleartrip.com), a bunch of hotels are returned. When I use the same API, i do not get any results. Why?

The API channel is not selected for Hotel rates and so, we do not get any search results.

How long do the APIs take to return results?

It depends on the availability of data in cache based on similar search criteria. We usually store information in cache for a short span since availability keeps changing.

We gather data from multiple suppliers in order to provide a wider range and more comprehensive set of hotels to our customers. The APIs however, will return data within 45 seconds.

Are the final cancellation charges returned in the response of the cancel API call?
No. It depends on fulfillment factors and supplier policies. The charges returned in the API call are purely indicative and are liable to change or vary in some cases.
Hotel search response returns "NET" and "SELL" in the "rate-type" field. What does it mean?
SELL rate hotels are fixed price hotels. Affiliates are not allowed to change the hotel price of SELL rate hotels. For NET rate hotels, they can add markup/discount.
Hotel search response contains fractions in the base-fare and in tax elements. How do we round up the price?

We recommend to calculate the total cost of the stay based on the exact amounts returned in the search response and round the price to the final amount.

Note: The Cleartrip API system will reject all bookings, where the API input booking amount is less than the Cleartrip calculated booking amount by more than 1 rupee. The Cleartrip API system will accept bookings, where the API input booking amount is greater than the Cleartrip calculated booking amount.

When a trip is cancelled the output XML contains an element <supplier-cancellation>F</supplier-cancellation>. What does it mean?
If the online cancellation of the trip is failed at the supplier end, then the system puts this cancellation into a manual queue from where it was eventually cancelled.
A booking request was made to the Cleartrip API, but no response was obtained. What do we do?
The calling programs presume that the booking is failed, if there is no response after the time-out period. We recommend that all calling programs send a reference ID for each transaction. If the responses are duly obtained, then the calling program should act based upon the HTTP response header and the response XML.