Check out some general and technical frequently asked questions and answers about Cleartrip API.
The Cleartrip Fligts API allows a user to search and book flights using a REST based service. XML is used for most (but not all) server/client communication. As a API consumer, you need an API key to use this service. You can read more about REST, XML and the API key in the Getting Started Guide.
Service URLs: The service is available at https://api.cleartrip.com/. Access to the staging (test) environment is available at http://api.staging.cleartrip.com/.
Schema files have been provided in two formats: RelaxNG Compact (RNC), and XML Schema Definition (XSD). Schema files have been defined wherever XML is required (either as request or response). All the schemas inherit from a common schema definition: air-common. The two schema files for air-common are air-common.rnc and air-common.xsd.
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 the search result will contain flights; there might not have been any flights found on that route). A successful search also returns
an XML response with the root element as air-search-result.
The various search parameters are described below:
| Name | Description | Format | Default | Example | Allowed values |
|---|---|---|---|---|---|
from |
Origin city or airport | A valid IATA code | (none) | BOM | |
to |
Destination city or airport | A valid IATA code | (none) | DEL | Cannot be the same as the from value |
depart-date |
Departure Date | A valid ISO date (YYYY-MM-DD) | (none) | 2008-10-20 | This should be a date within a year from the search date |
return-date |
Return Date. If you don't want to search for round-trip flights and instead just one-way flights, simply skip this parameter, or set it to null. |
A valid ISO date (YYYY-MM-DD) | null |
2008-10-30 | This should be a date within a year from the search date |
adults |
Number of adults | Valid integer not greater than 9 | 1 | 2 | |
children |
Number of children | Valid integer not greater than 9 | 0 | 1 | |
infants |
Number of infants | Valid integer not greater than 9 | 0 | 1 | Should not be greater than the number of adults. |
carrier |
Airline preference | Airline IATA code | Any | 9W | |
cabin-type |
Cabin type | Economy or Business | Economy | Business | |
permitted-carriers |
Allow results with only these carriers | yes or no | (none) | AI-IT-G8 | |
sort |
Sorts the search results in ascending or descending order of prices. The parameter is case sensitive and should match exactly as described in the Allowed values column. A search without this parameter or one which does not satisfy the allowed values will not sort the result. | String - asc or desc | (none) | asc | asc, desc |
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.
| Content type: | application/xml |
| Schema: | search-result.rnc, search-result.xsd |
| Sample XML: | search-result.xml,search-result.xsdsearch-result-international.xml |
Some error messages that you might get for an invalid search request.
| Error message | Description |
|---|---|
| Invalid IATA Code: XXX | XXX is not a valid IATA origin or destination code |
| Invalid date format: 08-09-12 | 08-09-12 is not a valid ISO date format. Valid ISO date format: YYYY-MM-DD |
| Invalid number of adults: one | “one” is not a valid integer value |
| Invalid number of children: two | “two” is not a valid integer value |
| Invalid number of infants: three | “three” is not a valid integer value |
| Invalid carrier code: Indian | “Indian” is not a valid IATA carrier code |
return-date far ahead in future | Date value cannot exceed 364 days from today’s date |
return-date less than depart-date | ‘return-date’ cannot be less than ‘depart-date’ |
| Origin and Destination should be different | ‘from’ and ‘to’ cannot have the same value |
| Number of Infants is more than the number of adults | ‘infants’ cannot exceed the ‘adults’ in a booking. |
| Total number of passengers cannot exceed 9 | Total number of passengers in a booking cannot exceed 9 |
The HTTP status code 400 (Bad Request) will be sent with the error messages written above.
Using the flights booking service requires the creation of an itinerary. An itinerary contains complete details about a flight booking, including flight, pricing, pax, contact, and payment details. The following actions can be performed on an itinerary:
Booking a flight(s) basically involves creating an itinerary and booking it. The view itinerary service can be used to view the itinerary details at any point. See below for a detailed description of each of these services.
The user sends an itinerary request (see the sample request XML and the schema) to create an itinerary on the Cleartrip servers. All the relevant booking details are collected from the user at this step. This includes
segment-spec element, which is under flight/flight-spec/segments in the itinerary request.. Note that a flight-spec corresponds to a flight in the search result response, while a segment-spec corresponds to a segment. Only the bare minimum information that is needed to uniquely identify a segment is needed.cabin-type element.pax-info tag under pax-info-list.contact-detail element.payment-detail element. Note that payment details at this step are optional. However, payment details are required on Book Itinerary.The user is not required to send the pricing information. That is calculated by the server itself after processing the itinerary request. The itinerary response provides all the relevant pricing details. The API user should check the pricing details (see payment-detail/amount) in the response to confirm whether pricing has remained the same as that on search or not.
Once an itinerary has been created, it is assigned an itinerary-id. Itinerary details can be fetched using the itinerary-id. Note, however, that an itinerary is available only for an hour after it has been created. At the end of one hour, an itinerary is expired and it is not possible to fetch its details (unless the itinerary was booked, at which point it becomes a trip, and its details can be fetched using the retrieve trip service).
(Note: Please go through the schema to know about basic input restrictions. This section details some further argument restrictions which cannot be provided by the schema.)
While creating itinerary, following xml validations are being done on server side. Please note that many of these might NOT be validated at the xsd schema level:
| Field | Validation | Reference |
|---|---|---|
cabin-type |
|
air-common.xsd |
| payment-type |
|
air-common.xsd |
credit-card-expiry-date |
|
air-common.xsd |
departure-and-arrival-airports (title) |
|
air-common.xsd |
airport-code |
|
air-common.xsd |
return-flight |
|
air-common.xsd |
flight-number |
|
air-common.xsd |
airline-code |
|
air-common.xsd |
departure-date |
|
air-common.xsd |
departure-date |
|
air-common.xsd |
return-date |
|
air-common.xsd |
pax-count |
|
air-common.xsd |
infant-count |
|
air-common.xsd |
date-of-birth |
|
air-common.xsd |
address |
|
air-common.xsd |
city, state, country, pin |
|
air-common.xsd |
title |
|
air-common.xsd |
name |
|
air-common.xsd |
phone-number |
|
air-common.xsd |
insurance |
|
air-common.xsd |
Upon successful creation of an itinerary, the server responds back with the itinerary details, alongwith the HTTP status code 201 (Created). The itinerary response contains the details provided by the user alongwith the pricing details. If any problem occurs while creating the itinerary, the body contains the error as its top-level element. Included inside it is a description of the error.
The response also contains the itinerary-id in the X-CT-ITINERARY-ID HTTP header. This id is used to identify the itinerary on the server. All further operations on the itinerary should be performed using this itinerary-id.
application/xmlApart from any schema validation errors, you can get one of the following errors.
| Error message | Description |
|---|---|
| API key invalid. | Please ensure that you are using the right key allocated to you for the right environment. Please do NOT publish your key on the support forums. Please contact api.support@cleartripcom with your api key and your user-id and we will investigate further. |
| Insurance not enabled. | Insurance is turned off on the Cleartrip system. Please retry your booking without insurance. |
| Seat sell / Pre-payment - failed | If the message contains the following - “Internal server error”, please contact api.support@cleartrip.com |
| Seat sell / Pre-payment - flight not available | The itinerary you selected (the combination of the booking class and the flight) is no longer available which means it is sold out - atleast temporarily. It is possible that this will become available in some time. |
| Seat sell / Pre-payment - price changed | The itinerary you selected (the combination of the booking class and the flight) is no longer available which means the particular class that you chose to book is sold out - atleast temporarily. It is possible that this will become available in some time. |
| Deposit Account invalid | Please use the proper deposit account number allocated to you. |
| Partial Booking | One or more of the flights you chose to book could not be booked with our suppliers. Please contact our customer support. Details @ http://www.cleartrip.com/support/. In case you would like to try booking again, please ENSURE that you cancel the successful portion of the booking BEFORE you book again. Please be aware that cancellation charges will apply. |
This service is used to view the details of any itinerary created on the server. The request URL is
If the itinerary is found, the itinerary XML is returned in the response body, alongwith the HTTP status code of 200. If the itinerary is not found, the status code 404 (Not Found) is returned, alongwith an error XML in the response body.
Round Trip Discount fares are special round trip fares. These are to be identified by farebasis code. Below are the patterns that need to be matched (using below regular expressions) with Farebasis code to identify roundtrip ONLY fares - King Fisher - {"IT":"^[A-Z0-9]+(R|RT)[A-Z0-9]*$"}
Sample XML with fare basis code for round trip special fare & normal fare: Round trip special fare for Kingfisher:
Normal fare:
| Airlines | Pattern |
|---|---|
| Jet Airways | { "9W":"^[A-Z0-9]+(R|RT)[A-Z0-9]*$"} |
| JetLite | {"S2":"^[A-Z0-9]+(R|RT)[A-Z0-9]*$"} |
| India Airlines | {"IC":"^[A-Z0-9]+(R|RT)[A-Z0-9]*$"} |
| Kingfisher | {"IT":"^[A-Z0-9]+(R|RT)[A-Z0-9]*$"} |
| Kingfisher Red | {"IT-RED":"^[A-Z0-9]+(R|RT)[A-Z0-9]*$"} |
| Jetways connect | {"9W-K ":"^[A-Z0-9]+(R|RT)[A-Z0-9]*$"} |
| Indigo | 6E --- Starts with N |
| Spice Jet | SG --- Starts with X |
| Go Air | G8 - ZGORNDPROMO |
For examples,
This service is used to book an itinerary already created on the server. The user’s payment details are also required at this point (see the sample request XML). If the itinerary is booked successfully, the response body returns the itinerary XML alongwith an HTTP status code of 200. This itinerary XML includes the trip-id (which is the permanent id for the booked itinerary, also known as a trip once it is booked). If the booking fails for any reason, an error XML is returned (although it is possible that the HTTP status code returned is still 200).
For a successful booking, the value of the booking-status element under each booking-info should be P. Alongwith this, the airline-pnr should also be available in the booking-info (although it is possible that the airline PNR could not be retrieved at the time the booking was confirmed, for which the API user should use the Retrieve Trip service to retrieve the PNR at a later time).
If the booking failed, this service will return an error block in the response body. However, the View Itinerary service will still return the complete itinerary XML. In this case, the value of each booking-status element should be H, which indicates failure.
The request body requires a booking XML with the payment details in it.
application/xmlWhile booking itinerary, following xml validations are being done on server side besides the xsd validation:
| Field | Validation | Reference |
|---|---|---|
contact-detail (mobile and landline) |
|
air-common.xsd |
card-expiry-date |
|
air-common.xsd |
| Similar to create itinerary. |
| Airline | Airline Code | Mandatory fields | XML for Mandatory fields | Sector |
|---|---|---|---|---|
Air India Express |
IX |
Paasport detail & Visa type |
sample-IX-book-change.xml | MAA-KUL |
Air Asia |
AK |
"Date of birth,Passport number,Passport expiry date and Visa type" |
sample-IX-book-change.xml | MAA-KUL |
Tiger Airways |
TR |
sample-IX-book-change.xml | BLR-SIN |
This service is used to retrieve the details of a trip. A trip is nothing but an itinerary which has been booked on the server. A trip-id is required to retrieve the trip details. For a successful booking, this trip-id is available in the trip-id tag in the itinerary response.
The request is a simple HTTP GET containing the trip-id in the URL.
application/xml| Error message | Description |
|---|---|
| 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 service is used to retrieve fare rules for a pricing-info using fare-key. This fare-key is available in the fare-key tag in search result.
The request is a simple HTTP GET containing the fare-key in the URL.
application/xmlThis service is used to cancel flights or the entire air booking from a trip. The cancellation can be a partial cancellation or a full cancellation
The request is an HTTP DELETE containing the comma separated booking-info-ids of the booking-info in the URL. Refer the response of the Retrieve Trip API to get the index of each booking-info.
application/xml| Response Code | Description | Response Content |
|---|---|---|
200 (OK) |
Cancellation successful | application/xml with root element cancellations |
400 (Bad Request) |
Requested URL invalid or incomplete | - |
401 (Unauthorized) |
Incorrect or no API key found in header | application/xml with root element faults |
403 (Forbidden) |
Cancellation not allowed due to violation of business rules or transaction rules | application/xml with root element faults |
404 (Not Found) |
Requested resource not found | application/xml with root element faults |
405 (Method Not Allowed) |
Method Not Allowed | - |
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 | - |