API Help & FAQ / Hotel API

General

What are the basic steps involved in integrating Cleartrip's Hotel API for distribution?
The following activities have to be executed by the interested party:
  • Inform Cleartrip's BD team of the intent to integrate.
    Contacts for the above are Aroonjit Singh Rosha (aroonjit.rosha@cleartrip.com) and Tarique Khatri (tarique@cleartrip.com)

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

A deposit account ID will be made available to you upon expressing intent to use the deposit account payment option.

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

You will be 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 payment is made using credit cards?
All refunds will be credited back to the credit card. Time duration for refunds is 5 working days from the time that fulfilment confirms cancelation to the customer.
How will refunds be managed if payment is made using deposit account?
All refunds will be credited back to the deposit account. Time duration for refunds is 24 hours from the time that fulfilment confirms cancelation to the customer.
How can we see the trips that have been booked using the Cleartrip API?

Cleartrip provides a dashboard for this purpose. You can view trips that have been booked, trip details, deposit account details etc using this dashboard. You will be presented with this dashboard automatically when you login into your account on Cleartrip.

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

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

Technical

Is there any API documentation or support forum?
Links for API documentation and support forum are as follows:
What kind of support turnaround time can I expect?

If you are in the integration phase and using Cleartrip staging environment, you can expect an email and or resolution within 24 hours.

If you are in production and using Cleartrip production environment, then you can expect email/resolution within 4 hours. (24x7)

What is the general process flow for api usage?
  1. First, a search call is made with parameters as specified in the API documentation.
  2. A rate rules call is then made with information obtained from the response of the search call. This call should be made within a few minutes (at most 28 minutes) of making the search call.
  3. A book call is then made with information obtained from the response of the search call. This call should be made within a few minutes (at most 28 minutes) of making the search call.
  4. A cancel call can be made as per the API documentation provided the cancellation rules are understood and accepted.
Where can we find a list of input cities?

You can find list of input cities at http://www.cleartrip.com/places/hotels/city_list.txt

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

You can find list of hotels that are available 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 detailed information about each hotel as detailed in the API documentation.

We have a property list of our own and we would like to match those with 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 on each of the hotels is available in the hotel xml.

Please note: If you are using this information and displaying it, 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 off of Cleartrip's website and just link to these on your own.

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

We are unable to access the staging URL for a search call. Help!

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. Is the URL encoded? It has to be. There is an example of how to do this in Java/Ruby in the API doc code samples.
  3. API Key – Is the API key (for the appropriate environment) being sent as part of the HTTP header? Refer to the API doc code samples.
  4. URLs – Are the requests being sent to the correct URLs? Please note the following URLs:

    for staging -

    for production -

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

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 far 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> 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.

In other words, 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.

We would like to track transactions on the API system with our own key. How do we do that?

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

You can retrieve the itinerary details using the same transaction id – Refer to question 17 above.

How do we view all the trips that we have 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 will list all the trips.

How do 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://staging.api.cleartrip.com/hotels/1.0/trips/D0805080031 or https://api.cleartrip.com/hotels/1.0/trips/D0805080031 as appropriate.

To retrieve the same details using your own transaction id (assuming you have passed it in the book call – refer to question 12), you can use http://staging.api.cleartrip.com/hotels/1.0/trips/ext/XXXXXXX or https://api.cleartrip.com/hotels/1.0/trips/ext/XXXXXXX as appropriate where XXXXXXX is your transaction id.

The book call is failing. Help?

Please check the following

  • Is the book URL accessibile? Can you ping the environment? If not contact your system administrator first.

  • 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 – Is the API key (for the appropriate environment) being 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:

    Are the parameters correct? Please refer to the API documentation for details.

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

    Are the parameters gathered from a search response obtained in the last 28 minutes?

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

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

Please Note: All the three XMLs need to be attached in order for support to get back to you.

What do the <high-rate> and <low-rate> elements represent in the search response?
These are indicative rates of the give hotel and are NOT meant to transact. That is also the reason why some of them might be Zero. These rates get updated over time and are NOT guaranteed by Cleartrip or by any other party. All transaction rates should be derived as explained in question 19.
Some rates do not contain a TAX element. What does that mean?
It means that the supplier of that rate has bundled the tax element into the base fare (BF) element and you should consider the TAX element to be Zero
How often do the city list, hotel list, hotel information etc change?
They tend to change often. These lists are regenerated on a daily basis
How do we get a "delta" of the changes to the above lists?
They are not available at this time.
HTTPS does not work for the book URL on staging? What do we do?
HTTPS is not enabled on the API interface for staging. Please use https://staging.api.cleartrip.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://staging.cleartrip.com), a bunch of hotels are returned. When I use the API, I don’t get any results. Help?

See question 18 above.

How long do the APIs take to return results?

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

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

Are the final cancellation charges returned in the response of the cancel API call final?
No. Depends on a lot of 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 is returning "NET" and "SELL" in the "rate-type" field. What do they 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 or tax elements. How do we round up?

We recommend that you calculate the total cost of the stay based on the exact amounts returned in the search response and round up/down the final amount.

Note that the Cleartrip API system will reject all bookings where the API input booking amount is less 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 this mean?
What this means that online cancellation of the trip failed at the supplier end. The system then puts this cancellation into a manual queue from where it is eventually cancelled.
A booking request was made to the Cleartrip API. But no response was obtained. What do we do?
This is not supposed to happen. But all systems have bad days. What we recommend is that the calling programs should assume that the booking failed if there is no reponse after a reasonable time-out period. This is also the reason why we recommend that all calling programs send a reference ID for each transaction. If responses are duly obtained then the calling program should act based upon the HTTP response header and response XML.