Flights API Reference

Contents

• Introduction
• Searching for flights
• Booking a Flight
• Create Itinerary
• View Itinerray
• Book Itinerary
• Retrieve Trip
• Retrieve Fare Rules
• Cancel Trip
• Sample Code

Introduction

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.

---

Searching for flights

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.

Request Details

Production URL:

https://api.cleartrip.com/air/1.0/search

Staging URL:

http://api.staging.cleartrip.com/air/1.0/search

Request method:

HTTP GET

Sample request

https://api.cleartrip.com/air/1.0/search?from=BOM&to=DEL&depart-date=2008-06-06&return-date=2008-06-06

Search parameters

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

Response details

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

Note : If the segments are priced together then you might get the pricing for those segments togther.

Error Messages

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.

---

Booking a Flight

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:

• Create Itinerary
• View Itinerary
• Book 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.

---

Create Itinerary

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

Flight details:

This includes details about every segment that the user wants to book. Segment details are provided using the 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.

Fare Key:

While creating the itinerary, the API user can pass the fare-key for each flight that he wishes to book(however this is optional). The fare-key is used to identify and check the pricing information for thar particular flight. If the fare-key is passed then the price check will be performed by the Cleartrip API, which verifies the price seen during searching. If the fare-key is not passed then the API user is responsible for doing the price check at their end and verify the flight being booked for any price change.

Cabin type:

The cabin type that the user wants to book (e.g. Economy, Business, etc.). This is provided under the cabin-type element.

Passenger (pax) details:

Details about all the passenger. For an adult passenger, just specifying the pax name and type (ADT) is enough. But for child and infant pax, the date of birth is also required. Details about each pax are provided under the pax-info tag under pax-info-list.

Contact details:

User contact details, e.g. contact name, email, address, mobile, etc. This is provided under the contact-detail element.

Payment details:

Only deposit account payments are accepted at this time. Under special circumstances credit card payments are accepted. Please email api.support@cleartrip.com for details. Payment details are provided under the 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).

Request Details

Production URL:

https://api.cleartrip.com/air/1.0/itinerary/create

Staging URL:

http://api.staging.cleartrip.com/air/1.0/itinerary/create

Request method:

HTTP POST

Schema:

itinerary-request.rnc, itinerary-request.xsd

Sample XML:

itinerary-request.xml,itinerary-request-international.xml

Input Restrictions

(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.)

1. Departure and Arrival Airport should not be same
2. Date value cannot exceed 364 days from today’s date
3. While booking a return ticket, the departure date for the return cannot be less than the departure for the onward journey
4. Age restrictions Child: 2 – 11 years, Infant: 0-23 Months
5. Mobile and Landline numbers should include the country and area code
6. Debit cards and International credit cards are not supported
7. Total number of passengers in a booking cannot exceed 9

Server Side Validation

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	Cabin type must be of length 1 and should be one of { E | P | B | F } or it must be passed as and exact keyword { Economy | Premium Economy | Business | First }.	air-common.xsd
payment-type	Payment type is invalid in the payment detail section. Payment must be made using a Deposit Account and the code DA should be passed. Note: Following the RBI regulation in Aug 2009, Credit Card payments ( code CC ) are allowed ONLY for mobile based transactions. Please send an email to api.support@cleartrip.com for details.	air-common.xsd
credit-card-expiry-date	Required field in case payment is made through a credit card. Card should be active and expiration date should be passed in the format YYYY-MM.	air-common.xsd
departure-and-arrival-airports (title)	Origin and destination airport codes should be different.	air-common.xsd
airport-code	Origin and desitnation airport codes must be valid IATA codes. Refer to http://www.cleartrip.com/common/json/airports.json as a reference.	air-common.xsd
return-flight	There must be a gap of atleast 3 hours between the arrival of the last flight of the onward journey and departure of the first flight of the return journey.	air-common.xsd
flight-number	Flight number should have a length of atleast 1 character. Required field.	air-common.xsd
airline-code	Invalid carrier codes. Please use http://www.cleartrip.com/common/json/airlines.json as a reference.	air-common.xsd
departure-date	Invalid departure date format. Please use YYYY-MM-DD only.	air-common.xsd
departure-date	Invalid departure date. For format, please use YYYY-MM-DD only. For validity, ensure that the departure date is in the next 300 days. Note: For some domestic flights a minimum of 3 hours is required between when you book and the flight departure time. For international flights, you will NOT get ANY results if you search for flights within 48 hours. Also note, our customer care timings are 7AM to 10PM IST if you need any assistance in your bookings.	air-common.xsd
return-date	Invalid return date. For format, please use YYYY-MM-DD only. For validity, ensure that the return date is greater than the departure date.	air-common.xsd
pax-count	Invalid number of passengers. Provide a valid integer between 1 and 9. Please note that some airlines restrict the number of passengets we request availability for. This will, in turn, restrict the number of results you get back from the Cleartrip API.	air-common.xsd
infant-count	The number of adults in a booking MUST be greater than the number of infants in a booking.	air-common.xsd
date-of-birth	If you are booking for children and or infants, a valid date of birth in the format YYYY-MM-DD must be provided. Note that the age of the child at the time of departure must be between 2 and 12 years and the age of the infant must be between 0 and 2 years at the time of departure.	air-common.xsd
address	Length of the address must not exceed 200 characters.	air-common.xsd
city, state, country, pin	City name is a required field and should be between 1 and 51 characters in length. State name should be between 1 and 51 characters in length. Country name is a required field. Pin code should be between 1 and 12 characters in length.	air-common.xsd
title	Title for adults, children and infants should be a valid value - one of the following { ( ADT : Mr , Ms , Mrs ), ( CHD, INF : Mstr, Miss ) }.	air-common.xsd
name	Name for adults, children and infants should be a valid value not exceeding 27 characters including title and should not contain ANY special characters or numbers.	air-common.xsd
phone-number	Either a valid mobile number or a valid landline number MUST be provided.	air-common.xsd
insurance	The insured tag should contain a valid value - one of { true | false }. The number of days for insurance is a mandatory field for international trips. It should be 90 days or the duration of the trip in case of round trips whichever is smaller. The max insurance days allowed for domestic trips is 30 days.	air-common.xsd

NOTE:

Optional elements:

While creating the itinerary the following elements are optional

• pax-info
• contact-detail
• payment-detail

If these parameters not provided at create itinerary then it must be provided during the book itinerary. Refer the XSD given in the Book Itinerary section.

But the user will need to provide the number of adults, children and infants in the request as parameters while calling the create itinerary.
Eg. https://api.cleartrip.com/air/1.0/itinerary/create?adults=2&children=1&infants=1

AirIndia Express Bookings:

• For a Domestic booking that contains AirIndia Express in any of the segment, the API user must pass the identification type and number for one of the Adult passengers travelling (Identifiction is required for ONLY 1 of the adult passenger referred to as the Master Passenger who will need to carry this identification while travelling).
• For an International booking that contains AirIndia Express in any of the segment, the API user must pass the Passport Number for all the travelling passengers.

Response Details

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.

Content type:

application/xml

Schema:

itinerary-response.rnc, itinerary-response.xsd

Sample XML:

itinerary-response.xml,itinerary-response-international.xml

Error Messages

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

---

View Itinerary

This service is used to view the details of any itinerary created on the server. The request URL is

Production URL:

https://api.cleartrip.com/air/1.0/itinerary/view/{itinerary-id}

Staging URL:

http://api.staging.cleartrip.com/air/1.0/itinerary/view/{itinerary-id}

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

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:

supp_AMADEUS_RT|si-dbf361ba-9c16-4e04-9fec-067bf81e5f7d|fk_IT_331_1324427700000_ERP14D_false__fpr_3935 Please note the pattern: ERP14D (fare basis code) *R*

Normal fare: supp_AMADEUS|si-dbf361ba-9c16-4e04-9fec-067bf81e5f7d|fk_IT_331_1324427700000_EAP14D_false__fpr_4185

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,

• Special RT fare: "supp_INDIGO|si-3bf33248-0d4a-4a41-bf4f-6b659655e805|fk_6E_184_1324428600000_N2BOMDEL_true_"

• Normal Fare: "supp_INDIGO|si-3bf33248-0d4a-4a41-bf4f- 6b659655e805|fk_6E_184_1324428600000_V0BOMDEL_true_"

• Round Trip Discount fare: supp_RADIXX|si-dbf361ba-9c16-4e04-9fec-067bf81e5f7d|fk_G8_106_1324468200000_ZGORNDPROMO_false__fpr_3408

Book Itinerary

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.

Production URL:

https://api.cleartrip.com/air/1.0/itinerary/book/{itinerary-id}

Staging:

http://api.staging.cleartrip.com/air/1.0/itinerary/book/{itinerary-id}

Method:

POST

Content type:

application/xml

Schema:

booking-request.rnc, booking-request.xsd

Sample XML:

booking-request.xml, booking-request-deposit-accounts.xml

Server Side Validation

While booking itinerary, following xml validations are being done on server side besides the xsd validation:

Field	Validation	Reference
contact-detail (mobile and landline)	One of mobile and landline is mandatory. Non-nemeric and special characters are allowed in mobile and landline but they will be stripped out. After stripping out, minimum and maximum length of landline must be 8 and 30 respectively. For mobile, minimum and maximum length of mobile must be 10 and 30 respectively.	air-common.xsd
card-expiry-date	card-expiry-date must not be in the past.	air-common.xsd

Error Messages

Similar to create itinerary.

---

Book request changes on few of the airlines

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

---

Retrieve Trip

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.

Production URL:

https://api.cleartrip.com/trips/air/view/{trip-id}

Staging URL:

http://api.staging.cleartrip.com/trips/air/view/{trip-id}

Method:

GET

Response Content type:

application/xml

Response Schema:

trip-response.rnc, trip-response.xsd

Response Sample XML:

trip-response.xml

Error Messages

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.

---

Retrieve Fare Rules

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.

Production URL:

https://api.cleartrip.com/air/1.0/itinerary/rules/{itinerary-id}

Staging URL:

http://api.staging.cleartrip.com/air/1.0/itinerary/rules/{itinerary-id}

Method:

GET

Sample Request:

https://api.cleartrip.com/air/1.0/itinerary/rules/ZG9tZXN0aWMtRzgtSy1LR09TQVZF

Response Content type:

application/xml

Response Schema:

fare-rules.rnc, fare-rules.xsd

Response Sample XML:

fare-rules-response.xml

---

Cancel Trip

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

Production URL:

https://api.cleartrip.com/trips/air/cancel/{trip-id}

Staging URL:

http://api.staging.cleartrip.com/trips/air/cancel/{trip-id}

Request Method:

DELETE

Sample Request:

Full Cancellation Request -

• Production: https://api.cleartrip.com/trips/air/cancel/{trip-id}
• Staging: http://api.staging.cleartrip.com/trips/air/cancel/{trip-id}

Partial Cancellation Request -

• Production: https://api.cleartrip.com/trips/air/cancel/{trip-id}?booking-info-ids=1,2
• Staging: https://api.staging.cleartrip.com/trips/air/cancel/{trip-id}?booking-info-ids=1,2

Response Content type:

application/xml

Response XML Schema:

cancellation.xsd

Response Headers:

Headers -

• X-CT-TRANSACTION-ID - Transaction ID of the cancellation
• LOCATION - Location of the cancelled resource

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	-

---

Sample code

Combined script (for ruby code):

ruby script

Go to top