Check out some general and technical frequently asked questions and answers about Cleartrip API.
The Cleartrip hotel API allows a user to search and book hotel rooms using a REST based service. XML is used for server/client communication. The user needs a key (known as the API Key), to use this API. You can read more about REST, XML and the API key in the Getting Started Guide.
Service URLs: The service is available at api.cleartrip.com. Access to the staging (test) environment is available at api.staging.cleartrip.com.
Schema files have been provided in XML Schema Definition (XSD) format. Schema files have been defined wherever XML is required (either as request or response).
This document is intended for Developers and business analysts working with affiliates/partners tasked with integration to the Cleartrip.com website.
A conceptual understanding of Internet and search technologies as well as strong familiarity with XML and HTTP protocol is necessary.
The API key is generated when the user’s API account is activated.
The API key should be sent as the value of the X-CT-API-KEY HTTP header with every API request.
Failure to send an API key will mean result in an HTTP 403 (Forbidden) response.
We suggest the following process/transaction flow in integrating with the Cleartrip APIs.
Provides the Cleartrip hotel search. The search request is a simple HTTP GET request.
The query parameters described below should be sent alongwith with the search URL, and the user’s API key in the HTTP headers.
A successful response will always return the HTTP status code 200.
(Note that a status code of 200 doesn’t necessarily mean that you the search result will be returned;
but a successful search will always return a status code of 200).
The various search parameters are described below:
| Name | Description | Format | Example |
|---|---|---|---|
check-in |
Check-in date | Valid ISO Date Format (YYYY-MM-DD) | 2008-11-01 |
check-out |
Check-out date | Valid ISO Date Format (YYYY-MM-DD) | 2008-11-04 |
no-of-rooms |
Number of rooms | Valid integer not greater than 4 | 2 |
adults-per-room |
Number of adults per room | Comma seperated list of valid integers. Number of items in the list should be equal to the number of rooms requested. | If the number of requested rooms is 2 and if one adult is going to stay in each room, then pass 1,1 |
children-per-room |
Number of children per room | Comma seperated list of valid integers. Number of items in the list should be equal to the number of rooms requested. | If the number of requested rooms is 2 and one child is going to stay in one of the rooms, with the other room not containing any children, then pass 1,0 |
city |
City name to search for hotels | Valid city name | Mumbai |
country |
Two letter ISO country code | Should be valid ISO country code | IN |
hotel-info |
This is an optional parameter which determines if hotel content information (either full or partial) is required as part of the search response or not. |
|
no / detail |
These are the restrictions on the search parameters.
If the search was successful, the response body returns an XML alongwith the HTTP status code 200.
If any error is encountered during search, the response body will contain an XML with the root element error.
See the schema and sample search result XML for more details.
application/xml
Some error messages that you might get for an invalid search request.
The HTTP response code in this case will be 400.
| Error message | Description |
|---|---|
| Not authorized to access the service | API Key Header is missing or invalid. |
| Invalid value for parameter check-in | Not a valid value for the parameter |
| Invalid value for parameter check-out | Not a valid value for the parameter |
| Invalid value for parameter no-of-room | Not a valid value for the parameter |
| Invalid value for parameter no-of-adults | Not a valid value for the parameter |
| Please specify the city | City is missing |
| Please specify the country | Country is missing |
| Please specify the check-in date | Check-in date is missing |
| Please specify the check-out date | Check-out date is missing |
| Please specify valid date range | Check-out date should be greater than Check-in date |
| Check-in date should be within 364 days | Check-in date exceeds maximum possible booking date. |
| Please specify no-of-rooms | No-of-rooms is missing |
| Please specify valid no-of-rooms | Valid values are 1-4 |
| Please specify adults-per-room | Adults-per-room is missing. Valid adults per room is 1-4. |
| Number of adults-per-room does not match no-of-rooms | This value should match the number of rooms in count, meaning if we request for 2 rooms, we need to specify 2 comma separated values for number_of_adults_per_room. viz: 1,2 |
| Please specify children-per-room | Children-per-room is missing. Valid children per room is 1-4. |
| Number of children-per-room does not match no-of-rooms | This value should match the number of rooms in count, meaning if we request for 2 rooms, we need to specify 2 comma separated values for number_of_adults_per_room. viz: 1,2. Note that even if the number of children is Zero, this needs to be specified as well, viz: 0,0 |
The hotel info request takes the hotel ID as input and provides the detailed hotel information along with the thumbnail and wide-angle image URL in response.
application/xmlThe booking system provides the ability to book a specified hotel room. Payment is required to book a hotel room using the Cleartrip hotel book API. Payment can be in the form of a credit card payment or a deposit account payment. Please refer to the API FAQ for further details regarding the payment options. API clients should ensure that the call made to the hotel book system is made over a secure SSL channel. Non-SSL requests for the book call will be rejected by the Cleartrip system. The booking response will contain the confirmation number or the specific error if the booking did not go through. For each transaction, if the payment mode is credit card, the card will be charged or if the payment mode is depost account, a debit entry will be made against the deposit account of the client user.
The various elements of the book request XML are described below:
| Name | Description | Format | Example |
|---|---|---|---|
affiliate-txn-id |
If the API integrator wishes to track bookings done through Cleartrip API system using an ID specific to their local system, that ID can be passed in this field. Note that this ID can later be used to retrieve details of the trip. | Valid alpha-numeric ASCII string | ABCDEFG2134 |
nri |
Whether the booking is made by/for an NRI | Boolean |
true |
hotel-id |
The search response returns a hotel-id along with each hotel found for the search criteria
that was matched. The hotel-id of the hotel selected for booking should be passed here.
|
Valid integer that was returned as a valid hotel-id in the search response. | 41002 |
check-in-date |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2008-11-01 |
check-out-date |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2008-11-04 |
number-of-rooms |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2 |
number-of-room-nights |
Acutal number of room-nights requested including all rooms across all dates requested.
In other words, if the search request was for 2 rooms for 2 nights, the room-nights value would be 2 * 2 = 4.
Note: the nights requested is not the arithmetic date difference between the |
Valid integer. | 4 |
adults-per-room |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 1,1 |
children-per-room |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 0,0 |
booking-code |
This value should be copied from the search response as-is. | Valid alpha-numeric string as returned from the search response. | :33719:26035:c:MAP:|M1_ |
room-type-code |
The room-type-code returned in the search response for the selected hotel and room-type. | Valid alpha-numeric string as returned from the search response for the selected hotel and room-type. | DBL-123 |
customer-ip-address |
The IP address of the caller. | Valid IP address in dot format. | 127.0.0.1 |
booking-amount |
This value should be calculated form the search response. This should be the total amount across number of rooms requested and number of nights requested for. This amount should also include taxes. If the total has a decimal, the amount should be rounded up to the next integer. | Valid integer. | 4000 |
customer |
Customer information. | See the sample XML for details. | - |
payment-type |
Should be the requested payment mode. | CC for credit card payments and DA for deposit account payments | DA or CC |
id |
If payment mode is deposit account, the deposit account id of the client needs to be passed. This number is obtained at the time of registration. Please read the API FAQ for further details. | Valid integer | 123123 |
password |
Ignore | - | - |
card-type-id |
If the payment mode is credit card, valid card-type-id should be passed.
|
Valid integer | - |
bank-id |
If the payment mode is credit card, this element can be ignored. | - | - |
number |
If the payment mode is credit card, valid card number should be passed. | Valid 16 digit credit card number | - |
expiration-month |
If the payment mode is credit card, valid expiration month of the credit card should be passed. | Valid 2 digit integer 01-12. | 08 |
expiration-year |
If the payment mode is credit card, valid expiration year of the credit card should be passed | Valid 4 digit integer representing the year. | 2011 |
card-id |
If the payment mode is credit card, the CVV found on the back of the card should be passed | Valid Integer | 353 |
name-on-card |
If the payment mode is credit card, the name on the card should be passed. | Valid string | Abcdefg Hijklm |
provisional-book-id |
Optional element, it is the provisional book id returned in the provisional book response. This element will be present only if provisional book api is called. | Valid string | 123456 |
If the book request was successful, the response body returns an XML alongwith the HTTP status code 200.
If any error is encountered during search, the response body will contain an XML with the root element error.
See the schema and sample search result XML for more details. An invalid request will result in a HTTP response status code of 400.
application/xml
Some error messages that you might get for an invalid search request.
The HTTP response code in this case will be 400.
| Error message | Description |
|---|---|
| Not authorized to access the service | API Key Header is missing or invalid. |
| Amount specified does not match actual booking amount | The calculated amount specified does not match the amount(s) sent back in the search response. |
| Invalid booking code specified | Booking code specified does not match the code sent in the search response. |
| Cannot find the hotel specified | Hotel specified is not valid or there is no inventory left for the specified rate. |
| Cannot find the room specified | Room type specified is not valid or there is no inventory left for the specified room-type. |
| No access to deposit account | Specified deposit account is invalid for the client user. |
This is an optional api. This api can be used by partners who take payment from the user at their end and then use deposit account to book the hotel from Cleartrip. It is not mandatory to use this api. But there can be scenarios where payment is taken from user and then booking fails because of unavailability. Using this api will eliminate that possibility. Card should be charged only if provisional booking is successful. If partners send the credit card details to Cleartrip and Cleartrip collects the payment then they can safely ignore this api. Cleartrip will do the provisional booking before charging the card.
application/xmlThe various elements of the rate rule provisional book request xml are described below:
| Name | Description | Format | Example |
|---|---|---|---|
nri |
Whether the booking is made by/for an NRI | Boolean |
true |
hotel-id |
The search response returns a hotel-id along with each hotel found for the search criteria
that was matched. The hotel-id of the hotel selected for booking should be passed here.
|
Valid integer that was returned as a valid hotel-id in the search response. | 41002 |
check-in-date |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2008-11-01 |
check-out-date |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2008-11-04 |
number-of-rooms |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2 |
adults-per-room |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 1,1 |
children-per-room |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 0,0 |
booking-code |
This value should be copied from the search response as-is. | Valid alpha-numeric string as returned from the search response. | :33719:26035:c:MAP:|M1_ |
room-type-code |
The room-type-code returned in the search response for the selected hotel and room-type. | Valid alpha-numeric string as returned from the search response for the selected hotel and room-type. | DBL-123 |
The response will contain the provisional booking id. This id has to be passed in book request. A valid response can contain empty string as provisional book id. In such cases please send an empty string as provisional book id in the book request.
application/xmlThe possible error messages are similar to the book request messages.
This call will return the cancellation policy and the allowed payment modes for booking a given hotel room.
application/xmlThe various elements of the rate rule policy request xml are described below:
| Name | Description | Format | Example |
|---|---|---|---|
nri |
Whether the booking is made by/for an NRI | Boolean |
true |
hotel-id |
The search response returns a hotel-id along with each hotel found for the search criteria
that was matched. The hotel-id of the hotel selected for booking should be passed here.
|
Valid integer that was returned as a valid hotel-id in the search response. | 41002 |
check-in-date |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2008-11-01 |
check-out-date |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2008-11-04 |
number-of-rooms |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 2 |
adults-per-room |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 1,1 |
children-per-room |
See search request parameters for details. | This should exactly the same value as that passed as part of the search request. | 0,0 |
booking-code |
This value should be copied from the search response as-is. | Valid alpha-numeric string as returned from the search response. | :33719:26035:c:MAP:|M1_ |
room-type-code |
The room-type-code returned in the search response for the selected hotel and room-type. | Valid alpha-numeric string as returned from the search response for the selected hotel and room-type. | DBL-123 |
The response will contain the cancellation policy along with the payment modes supported for the book call.
application/xmlThe possible error messages are similar to the book request messages.
This call will reutrn the details of a given hotel booking. The input can either be the Cleartrip trip reference ID or the external transaction reference ID passed during booking by the client.
The response will contain the itinerary details of the hotel booking.
application/xml
Some error messages that you might get for an invalid search request. The HTTP response code in this case will be 400.
| Error message | Description |
|---|---|
| Not authorized to access the service | API Key Header is missing or invalid. |
| Trip for trip id xxx not found! |
Trip-ID XXX doesn’t exist.
The HTTP status code sent will be 404 (Not Found) is returned with this error.
|
This call can be used for cancelling a previously booked hotel room. The service does not allow partial cancellations. The input to this will be the Cleartrip trip reference ID. Cancellation of a given trip will be allowed only if the user cancelling (identified by the API key sent in the HTTP header) is the same user who made the original booking.
Note: The cancellation charges that are returned in the response are indicative cancellation charges and the final charges may vary in some cases.
application/xmlIf the cancellation was attempted and it failed, the cancellation will be actioned manually and the API will NOT show the refund amount in the XML.
| Error message | Description |
|---|---|
200 (OK) |
Cancellation successful |
400 (Bad Request) |
Requested URL invalid or incomplete |
401 (Unauthorized) |
Incorrect or no API key found in header |
403 (Forbidden) |
Cancellation not allowed due to violation of business rules or transaction rules |
404 (Not Found) |
Requested resource not found |
500 (Internal Server Error) |
Server encountered and internal error while attempting to process the request |
501 (Not Implemented) |
Cancellation for this type of resource is not supported |
Notes: For using the java code, use your basic authentication username/password in utility.java and your API key in each of the requests. In case you are using the ruby code, ensure that the basic auhentication username, password and API key are entered in each of the requests.