4 · Search

Search flights.

What: find bookable offers for a route, date(s) and passenger mix across every supplier you have enabled.

When: the start of every booking — or on its own to display fares.

Before / After: optionally call /origins + /destinations to build the form → here → pick one offer and send its offerId → /fare-quote.

Gotchas

• Read the new names — the old ones are removed in the next release. Each new name has the same value as its old one until then, and the reference marks the old name deprecated. price (totalAmount, currency, baseFare, taxes, commission, tds, netPayable, publishedTotal, passengerFares[{ passengerType, count, perPerson, total, baseFare, taxes }], infantFare — each null when the seller did not state it) for pricing; legs[] and segments[] origin / destination ({ iataCode, name, city, countryCode, timezone }) for originCode / originName / departureTimezone and destCode / destName / arrivalTimezone; segments[].departureTerminal / arrivalTerminal / cabin for originTerminal / destinationTerminal / cabinClass; marketingCarrier.iataCode for marketingCarrier.code; a technical stop’s airport for airportCode / airportName; policy.refund / policy.change for policy.refundPolicy / changePolicy; isInternational for requiredPassengerFields.international; booking.requestBooking (beside booking.bookable) for booking.viaSupplierApi: false; supplierCode for sourceCode; seller for supplier. price holds every part of pricing: netPayable, publishedBaseFare / publishedTaxes, taxBreakdown[] (taxComponents), commercials[] (with passengerType, owner) and each row’s baseFare / taxes. Carriers are one shape { iataCode, name, flightNumber } (null, never "", when not stated); airport objects take every fact from the Kitionz airport list (null when the airport is not in it). The offer-level cabin, a leg’s cabinClass and fareFamily.cabin are removed in the next release: read each flight’s cabin.
• tripType is optional. Leave it out and you get every trip kind leaving on departureDate: one-way fares AND round-trip offers. ROUND_TRIP gives round trips only.
• ONE_WAY can also return round trips. Some suppliers answer a one-way search with round-trip packages too. Kitionz returns them: each says tripType: "ROUND_TRIP" and has its returnDate. Read tripType on every offer and show it as what it is; never assume an offer is the kind you searched. To get every package, send ROUND_TRIP or leave tripType out: a supplier that keeps one route list per trip kind is asked in a one-way search only where its one-way list has the route and date.
• returnDate is the day your traveller flies back. With it, every round-trip offer has that returnDate: the local date its return leg leaves. Round-trip offers that return on other days are not in offers: meta.otherReturnDates counts them per day. Search again with that returnDate to see them. otherReturnDates counts only the round trips suppliers already sent; it is not a calendar of every return day. Without a returnDate, you get the round trips leaving on departureDate, each with its own returnDate.
• A returnDate with no tripType is a return journey: one-way offers and the round trips back on returnDate. Read each one-way offer’s route (legs[0].origin.iataCode → destination.iataCode); never assume it flies your way out. Today they all do; one-way offers flying back will come in this same answer later. A returnDate is refused (400) with tripType: "ONE_WAY", and with slices (the date of your second slice is your return date).
• Each offer says which trip it is: tripType (ONE_WAY | ROUND_TRIP), departureDate, and — for a round trip — returnDate, fixed by the fare. A round trip’s price covers both ways: label it so in your screen. Send departureDate back unchanged on /fare-quote and /book. Book each offer by its own labels: send the offer’s tripType and returnDate, never the search’s. They may be left out there (the offer’s own are used); when sent they must be the offer’s (a different trip → 400 OFFER_TRIP_MISMATCH).
• A round trip is ONE offer with legs: [OUTBOUND, RETURN], one totalAmount, one offerId: one fare for both ways, booked with one /fare-quote and one /book. It can be a series package (seats bought in advance and sold as a pair) or a return fare. Never staple two one-ways together.
• Today round trips come only from suppliers whose catalogue offers them. With tripType: "ROUND_TRIP", every other supplier is listed in meta.suppliersExcluded with reason ROUND_TRIP_NOT_OFFERED (left out, not a failure).
• Some suppliers need your return date to find round trips. With a returnDate, Kitionz asks them for that day only, never for other days, so their other return days are not in otherReturnDates. When Kitionz already holds such a supplier’s list of return days and your day is not on it, the supplier is not asked and is listed in meta.suppliersExcluded with reason RETURN_DATE_NOT_LISTED (left out, not a failure).
• A supplier whose fares are all of a category your filters.inventoryCategories (or your connection) leaves out — e.g. a series-only supplier when you ask for ONLINE — is not asked at all: it is listed in meta.suppliersExcluded with reason INVENTORY_NOT_REQUESTED (left out, not a failure).
• A supplier that publishes a date list is asked on every date its list shows. When its current list leaves the date out, it is not asked and is listed in meta.suppliersExcluded with reason DATE_NOT_LISTED (left out, not a failure). A supplier with no date list is asked on every one-way search (a round trip goes only to suppliers whose catalogue offers round trips, see above).
• Some suppliers return their round-trip packages together with their one-way fares, from one date list for both. Their listed dates count for both trip kinds: a tripType: "ROUND_TRIP" search asks them on any listed date, and a search with no tripType asks them once and returns both kinds.
• With slices the slices decide the kind (one slice = one-way, two = round trip); send tripType only if it agrees. The first slice must be the same trip as origin, destination and departureDate, and a second slice must be its exact way back. Never send returnDate with slices: the date of your second slice is your return date, and meta.otherReturnDates is filled for it too. Refused (400): three or more slices, and a second slice to other airports (open jaw) — multi-city search is not available.
• Filters work for every supplier. Kitionz applies cabin and every filters field to the offers suppliers return: cabin reads the offer’s own cabin when it states one, otherwise each flight’s cabinClass (a cabin not stated keeps the offer); refundableOnly keeps only REFUNDABLE (NOT_GIVEN — not stated — is left out); maxConnections counts changes of flight per direction (0 = no change of flight; a technical stop on the same flight is allowed; a stop with no airport stated counts); airlines.include / exclude read each flight’s marketing carrier; fareBrandsInclude / Exclude read fareFamily.code; maxOffersPerSupplier keeps each supplier’s cheapest. An empty list is no filter; a filter name Kitionz does not know is refused (400). meta.suppliers[].offerCount counts the offers left after your filters.
• meta.filtersApplied says what each filter removed: one entry per filter you sent, { field, removed } — an offer two filters remove counts under both. Read it when an answer is empty: few suppliers state a fare brand or a refund policy, so fareBrandsInclude or refundableOnly can remove every offer, and the entry says so.
• maxOffersPerSupplier with no tripType: one-way fares and round-trip packages share one price list per supplier, so a small number can leave out every package (packages usually cost more). Send tripType to cap one kind only.
• An airport code Kitionz does not know (not an IATA airport or city code it has) is not refused today: suppliers are still asked, and the envelope meta.diagnostics carries UNKNOWN_AIRPORT naming the field and the code. Check the code. A real airport nobody sells from returns 200 with no offers and no such diagnostic. The same holds on /destinations and /availability.
• meta.tripTypes lists the kinds this search covered; each meta.suppliers, meta.suppliersFailed and meta.suppliersExcluded entry carries the tripType of its part (one supplier can appear once per kind) — so the same supplier can be in suppliersSucceeded (one kind answered) and in suppliersFailed (the other failed). supplierCounts, when present, counts distinct suppliers in each list. A DEADLINE_EXCEEDED entry with tookMs: 0 means the search ran out of time before that part asked the supplier.
• Search prices are indicative — never charge off them; re-price at /fare-quote.
• Pax fields are adults / children / infants (same names across the whole flow).
• Search with the passengers you will book. An offer is quoted and booked only for the adults, children and infants it was searched for; another party gets 400 PASSENGER_COUNTS_CHANGED at /fare-quote and /book (for every supplier). Each offer’s expiresAt says when Kitionz stops accepting its offerId (not a price guarantee).
• With infants, read price.infantFare.status. PRICED: the supplier’s infant price is the INFANT row of price.passengerFares and inside price.totalAmount. NOT_GIVEN: the supplier gave no infant price, so that row’s total is null and price.totalAmount covers adults and children only. Add your own infant charge (the supplier or airline may still charge for the infant), or hide such fares — your choice. Kitionz never hides a fare and never shows ₹0 for a missing infant price. Treat any other status as NOT_GIVEN, and add your infant charge before you sort by price.
• Count each passenger by age on the last flight of the trip (the return flight on a round trip): ADULT 12 or older, CHILD 2–11, INFANT under 2. A baby who turns 2 before the return is a CHILD for a round trip but an INFANT for a one-way fare — when one search returns both, the party you sent fits only one of them; /book refuses the other.
• supplierCodes is optional — leave it out. Kitionz already knows which suppliers your key is enabled for and searches all of them. Send supplierCodes only to narrow to a subset of THOSE (blanks ignored; a non-enabled code → 403). Don’t send the empty [""] from the example skeleton. (sources is its old name, accepted until the next release.)
• Each offer carries capabilities { seatSelection, meals, extraBaggage, hold, fareRules, cancellation: REALTIME|OFFLINE|NONE } — a supplier-level hint; the exact per-offer answer comes at /fare-quote (eligibility), and /book rejects an unsupported action with a typed 422 (e.g. HOLD_NOT_SUPPORTED_FOR_THIS_OFFER). Use hold and cancellation. Do not build seat, meal or extra-baggage selling on this: no Live supplier offers them today (only Kitionz Test Air shows a seat map), and /book takes no seats, meals or bags.
• How an offer books: read booking.bookable FIRST. bookable: false → show the fare, don’t offer to book it (requestBooking is then false). bookable: true + requestBooking: false → /book books with the supplier; the booking’s status tells you whether the PNR came back on that call or follows. bookable: true + requestBooking: true → /book records a request (PENDING_FULFILMENT); book on the supplier’s portal, then /bookings/:id/fulfil. In code: if (!booking.bookable) … else if (booking.requestBooking) … else …. (booking.viaSupplierApi is the old name: false where requestBooking is true, absent when not bookable.)
• The same flights often come back from several sellers — Kitionz returns every offer and never removes a copy. Group them by journeyKey: equal keys mean the sellers state the same flights at the same start and end times (same airline and flight number, same airports including stops, each leg leaving and arriving at the same local time). Price, seats, baggage and rules differ per offer: never add seats across a group, and book one specific offer with its own offerId. Each leg has a legKey (same rule, one direction) — equal leg keys never let you split a package or join two one-ways. When journeyKeyComparable is false (reasons in legs[].legKeyGaps) the key is unique to that offer: show it on its own. The key changes when an airline retimes a flight or Kitionz learns a fact a seller left out. The recipe (version jk1) is published so you can key your own inventory the same way.

Example — request (only origin / destination / departureDate / adults are required):

{ "origin": "DEL", "destination": "BOM", "departureDate": "2027-01-15", "adults": 1 }

Response (trimmed) — send an offer’s offerId to /fare-quote. Read the new names shown; until the next release each flight also carries its old names (here marketingCarrier.code, originCode, destCode):

{
  "data": {
    "searchId": "srch_x6xpERXqk",
    "offers": [ {
      "offerId": "floffer_9x2k7q",
      "tripType": "ONE_WAY",
      "departureDate": "2027-01-15",
      "journeyKey": "jk1_59da15eff41394c5648af3caaab489ca",
      "journeyKeyComparable": true,
      "price": { "totalAmount": 5480.00, "currency": "INR", "baseFare": null, "taxes": null, "passengerFares": [ { "passengerType": "ADULT", "count": 1, "perPerson": 5480.00, "total": 5480.00 } ], "infantFare": null },
      "isInternational": false,
      "policy": { "refund": "NOT_GIVEN", "change": "NOT_GIVEN" },
      "legs": [ {
        "legType": "OUTBOUND",
        "origin": { "iataCode": "DEL", "name": "Indira Gandhi International Airport", "city": "New Delhi", "countryCode": "IN", "timezone": "Asia/Kolkata" },
        "destination": { "iataCode": "BOM", "name": "Chhatrapati Shivaji Maharaj International Airport", "city": "Mumbai", "countryCode": "IN", "timezone": "Asia/Kolkata" },
        "departureTime": "2027-01-15T06:00:00+05:30", "arrivalTime": "2027-01-15T08:10:00+05:30",
        "segments": [ { "marketingCarrier": { "iataCode": "6E", "code": "6E", "flightNumber": "2134" }, "originCode": "DEL", "destCode": "BOM", "departureTerminal": "1", "arrivalTerminal": null, "cabin": null } ],
        "legKey": "lk1_59da15eff41394c5648af3caaab489ca", "legKeyComparable": true, "legKeyGaps": []
      } ],
      "capabilities": { "seatSelection": false, "hold": false, "cancellation": "OFFLINE" },
      "booking": { "bookable": true, "requestBooking": false, "validatingCarrier": null }
    }, {
      "offerId": "floffer_4h8n2r",
      "tripType": "ROUND_TRIP",
      "departureDate": "2027-01-15",
      "returnDate": "2027-01-19",
      "price": { "totalAmount": 9940.00, "currency": "INR" },
      "legs": [ { "legType": "OUTBOUND" }, { "legType": "RETURN" } ],
      "booking": { "bookable": true, "requestBooking": false }
    } ],
    "meta": { "tripTypes": ["ONE_WAY", "ROUND_TRIP"], "suppliersFailed": [], "otherReturnDates": [] }
  }
}

Example — a return journey (one-way offers and round trips back on 19 Jan):

{ "origin": "DEL", "destination": "BOM", "departureDate": "2027-01-15", "returnDate": "2027-01-19", "adults": 1 }

Response (trimmed) — one round-trip offer comes back on 19 Jan; two others come back on 20 Jan and are only counted:

{ "data": { "offers": [ { "tripType": "ONE_WAY", "departureDate": "2027-01-15" }, { "tripType": "ROUND_TRIP", "departureDate": "2027-01-15", "returnDate": "2027-01-19" } ], "meta": { "tripTypes": ["ONE_WAY", "ROUND_TRIP"], "otherReturnDates": [ { "returnDate": "2027-01-20", "offerCount": 2 } ] } } }