Flights reference

The rules that apply to many Flight API calls. Each call’s page links here. Every call is on the Flights overview.

Trip kinds

• A one-way offer has tripType: "ONE_WAY" and one leg.
• A round trip has tripType: "ROUND_TRIP", two legs, one price for both ways and a fixed returnDate. Book it as one offer; never join two one-way offers.
• On Search, leave tripType out to get every kind, each offer labelled. ONE_WAY returns one-way offers only, ROUND_TRIP round trips only.
• Origins and Destinations say which kinds leave from each airport (tripTypes), and Available dates says it for each day.

Lists and Search

• Another airport of the same city. An offer can fly from or to another airport of the city you searched: DEL can return HDO, BOM NMI, GOI GOX, and DXB SHJ or AUH. Show the airports in each offer’s legs, never the code you searched.
• Suppliers without lists. Origins, Destinations and Available dates show only what suppliers publish in their route and date lists. Suppliers without such lists are searched on every route and every day, so Search can find flights those calls do not list. Do not build a closed drop-down from them.
• Lists are not seats. A listed airport or day comes from the suppliers’ own lists. Search asks the suppliers live, so a listed day can still have no seats.

Empty answers

An empty list is a 200, not an error. The outer meta.diagnostics says why. For example:

Treat a code you do not know as information only.

Supplier lists in answers

Most organisations see the supplier only after booking. Their answers have empty supplier lists and supplierDisclosure: "AFTER_BOOKING": Origins, Destinations and Available dates in meta.suppliers; Search in data.meta (suppliersCalled, suppliersSucceeded, suppliersFailed, suppliersSkipped, suppliersExcluded), with the totals in data.meta.supplierCounts. A supplier that fails never fails the whole call: the others still answer.

Booking status and next action

Every booking has status and nextAction. Do what nextAction.code says.

Most pending bookings settle within 10 minutes. Still pending after 20 minutes: contact Kitionz support with the booking id. What to do with your customer’s money in each status is on the Flights overview.

Passengers

• Types. ADULT is 12 or older, CHILD 2–11, INFANT under 2, by age on the date of the last flight (the return flight on a round trip). A passenger whose age does not fit the type answers 422 PASSENGER_FIELD_REQUIRED (”… Search again with this passenger as a child.”): search again with that count. Fare quote and Book are for the party you searched with: leave adults, children and infants out, or send the same numbers; other numbers answer 400 PASSENGER_COUNTS_CHANGED. At most 9 adults and children in one booking.
• Infants. Each infant sits on an adult’s lap: send guardianPassengerIndex, the position in passengers (0 = the first) of that ADULT. One infant per adult. An infant who turns 2 before the return flight travels as a CHILD.
• Names. lastName is optional in the API, but most sellers refuse a booking without it: send firstName and lastName for everyone. A traveller with one name: send it as both.
• Titles. Mr, Mrs or Ms for adults; Master (boy) or Miss (girl) for children and infants. Kitionz sets gender from the title; with any other title (Dr, Prof), send gender (MALE or FEMALE).
• Date of birth. A CHILD or INFANT always needs dateOfBirth. A domestic ADULT sent without one is sent to the seller with 1 January of (this year − 20), because some sellers refuse a booking without a date of birth. The booking answers dateOfBirth: null with dateOfBirthDefaulted: true for that passenger, so you never show a date nobody gave.
• Contact. The seller receives your organisation’s registered email and mobile as the booking contact, not booker.email. E-tickets, schedule changes and cancellations from the seller or the airline come to you: pass them on to your traveller. booker.phone is sent only when your organisation has no mobile on record, and some sellers receive booker.name as the contact name; otherwise booker is your record of who made the booking. Phone numbers: an Indian mobile, 10 digits, +91 optional.
• International trips. Every offer has isInternational (true when a flight crosses a border, or when Kitionz cannot tell) and requiredPassengerFields.fields, each MANDATORY or OPTIONAL. On an international offer every passenger needs dateOfBirth, passportNumber, passportExpiryDate and nationality, and the passport must be valid at least 6 months after the last flight. Send countries as two-letter codes (IN, not Indian). Leave passportIssuingCountry out unless the passport was issued by another country than nationality. Collect all of this before you take payment: a missing field answers 422 PASSENGER_FIELD_REQUIRED, a passport that expires too soon 422 PASSPORT_EXPIRY_TOO_SOON; error.details.invalidFields lists every passenger and field, and nothing is sent to the seller.
• Test is lenient. Kitionz Test Air accepts any title, phone or country. Live sellers refuse a detail they cannot take with 400 BOOK_PASSENGER_TITLE_UNSUPPORTED, BOOK_CONTACT_PHONE_UNSUPPORTED or BOOK_PASSENGER_COUNTRY_UNSUPPORTED: follow these rules in Test too.

Times and money

• Times. A flight’s departureTime and arrivalTime are the airport’s local clock with its UTC offset (2027-01-15T06:00:00+05:30), and each flight’s origin.timezone / destination.timezone name the zone. Show the clock time as written; never convert a flight time to your server’s or your user’s zone. departureDate and returnDate are local dates at the departure airport. Kitionz’s own times (expiresAt, quoteTokenExpiresAt, nextAction.deadlineAt, createdAt) are UTC, ending in Z.
• Money. Every amount is Indian rupees (currency: INR): a number with up to two decimals, so 4511.86 is ₹4,511.86 — not paise. A gateway that takes paise needs the amount × 100, worked out with exact decimals. Charge from the fare quote’s price.totalAmount; never add up the parts yourself. Offers, fare quotes and bookings carry the same price block.
• Per-passenger prices. price.passengerFares has one row per passenger type (passengerType, count): total is the price of all passengers of that type together and perPerson is one passenger’s, to the paisa. When every row states a total, the rows add up to totalAmount. Charge totalAmount, never a sum of perPerson.

Test every outcome

In Test, nothing is booked for real: each Kitionz Test Air offer rehearses one outcome. Search a Test Air route, then pick the offer whose fareFamily.code is the outcome you want. Several offers carry TEST_CONFIRM (a second seller, and the shapes Live sellers send): all book like it. Round-trip packages leave on fewer days and offer only the outcomes marked in the last column.

An offer with booking.requestBooking: true (Kitionz Test Portal) rehearses a request booking: Book answers PENDING_FULFILMENT, and Submit PNR with a PNR such as TESTA7K2Q9 confirms it.

Errors every call can return

Every error has error.code, error.message and error.request_id. Quote the request_id when you write to support@kitionz.com. Every code: Error codes.

Renamed fields

Answers carry the old names beside the new ones until the next release. These pages use only the new names, and their examples leave out every field the API reference marks deprecated. “The next release” is the next Flight API update that removes the old names. It has no date yet. Move to the new names now: until then both work, and sending an old and a new name with different values is 400 VALIDATION_ERROR.

Requests, renamed on 2026-10-27

Not needed: originCode, destCode on Book (Kitionz takes the route from the offer). No longer accepted (400): selectedSeats, selectedSSRs, formOfPayment, privateFareCodes, passengers[].frequentFlyer on Book, and departureDate on Fare rules and Seat map.

Answers, renamed on 2026-10-28

Every answer carries the new name beside the old one, with the same value. The next release removes the old one: read the new names now.

Not renamed yet (the next release changes these too):

• Bookings show bookingMode: "LIVE" for a booking made with INSTANT, and the fare quote’s eligibility.bookingModesSupported says LIVE for what /book calls INSTANT.
• Baggage rows use paxType ADT, CHD, INF for ADULT, CHILD, INFANT.
• Search data.meta supplier lists (suppliersFailed, …) and GET /v1/flights/suppliers rows still name the supplier sourceCode.
• Webhook booking events (flight_booking.confirmed, flight_booking.rejected) still name the seller supplier and returnSupplier.

Glossary