Reference · step 2 of 9

POST/flights/search

{{base_url}}/flights/search

One request, complete results: options grouped by the journeys their fares cover, each fare priced once for the whole option with a journey view; the per-flight segment view on request. The UI uses the streaming route instead; this one waits for all suppliers.

Headers

Content-Typeapplication/json
AuthorizationBearer {{token}}
Body (6 notes)
  • detail: journey (default) = one set of fare attributes per fare option; segment = also segments[] inside each fare option, one entry per flight. Any other value is a 400 (field detail, rule one_of).
  • include_fare_rules: default true; false leaves fare_rules out of the reply and off every fare.
  • segments: 1 to 6 legs; a return trip is two segments. date is YYYY-MM-DD.
  • adult 1-9 (required), child 0-9, infant 0-9.
  • cabin_class: 1 economy, 2 premium economy, 3 business, 4 first; 0 or absent = no filter.
  • fare_types: 1 regular, 2 student, 3 senior citizen, 4 doctor/nurse, 5 armed forces; absent = regular.
Reply (8 notes)
  • results[] groups options by the journey indexes their fares cover: one way = one group [0]; a return sold per direction = groups [0] and [1]; a combined return fare = one group [0, 1]. Pick one option and one fare per group until every requested journey is covered.
  • option_id identifies the flights, price_id the fare on them; both go to /flights/reprice. Ids are valid until valid_till (60 minutes).
  • A fare prices the whole option: one object per requested passenger type (adult, child, infant), each with its fare (base, taxes, total, net, pax_count), booking_class, fare_basis and baggage. No amount appears anywhere else, never inside segments[].
  • Segment view (detail=segment): segments[] on every fare, one entry per flight matched by segment_index, same fields per flight.
  • fare_rules on a fare maps each journey index to an id (fr_1, fr_2, …) in the top-level fare_rules; a missing index has no rule known at search. Ids mean nothing outside this reply.
  • Baggage is {kg} and/or {pieces}; absent = not included or not known. Flight segments carry airport codes only (from, to).
  • Times are local to the airport, format YYYY-MM-DDTHH:MM:SS, no zone; valid_till carries its offset.
  • A missing field is zero, false or not applicable. The reply has no $schema field.
Keys and what they mean
Request
keytypewhen presentimportancemeaning
segments[]arrayrequired, 1 to 6must readThe legs you search: one for one way, two for a return (second from the destination back), up to six for a multi-city trip.
segments[].fromstringrequiredmust readDeparture airport, IATA code.
segments[].tostringrequiredmust readArrival airport, IATA code.
segments[].datedaterequiredmust readDeparture date, YYYY-MM-DD, local to the departure airport.
adultintegerrequired, 1 to 9must readAdults travelling. child and infant default to 0; an infant needs an adult.
cabin_classintegeroptionaluseful1 economy (default), 2 premium economy, 3 business, 4 first.
detailstringoptionalusefuljourney (default) or segment. segment adds segments[] inside every fare option with the fare attributes per flight.
include_fare_rulesbooleanoptional, default trueinformationalfalse leaves fare_rules out of the reply and off every fare; smaller reply.
Total: 8 keys
Reply
keytypewhen presentimportancemeaning
search_idstringalwaysinformationalId of this search, for support questions.
valid_tilldatetimealwaysmust readUntil when an option_id and price_id of this reply can be sent to reprice. After it, search again.
fare_rulesobjectunless include_fare_rules is falseusefulEvery distinct fare rule of the reply keyed by id (fr_1, fr_2, …). Fares point at them; ids mean nothing outside this reply.
results[]arrayalwaysmust readOne group per set of journeys the fares cover. Pick one option and one fare from each group until every journey of your request is covered.
results[].journey_indexesarray of integeralwaysmust readWhich journeys of your request this group's fares cover: [0] onward only, [1] return only, [0, 1] a combined fare for both.
results[].options[].option_idstringalwaysmust readNames the flights of this option. Send it to reprice with the price_id of the chosen fare.
results[].options[].segments[]arrayalwaysmust readThe flights of this option in order, each named by (journey_index, segment_index); segment_index restarts at 0 in every journey.
results[].options[].segments[].operating_airline_codestringonly on a codeshareusefulThe airline that flies the aircraft when it differs from airline_code, the airline selling the seat. Show it to the traveller.
results[].options[].fare_options[]arrayalwaysmust readThe fares sold on exactly these flights. Each prices the whole option once; no amount appears anywhere else.
results[].options[].fare_options[].price_idstringalwaysmust readNames this fare. Send it to reprice with the option_id.
results[].options[].fare_options[].adultobjectalwaysmust readWhat this fare gives an adult: fare (the price for the whole option), fare_ref, refundable_type, cabin_class, booking_class, fare_basis, baggage. child and infant appear only when requested.
results[].options[].fare_options[].adult.fare.total_farenumberalwaysmust readWhat the traveller pays for one adult on this option, taxes included.
results[].options[].fare_options[].adult.fare.net_farenumberalwaysmust readWhat you pay us for one adult: total_fare less your commission.
results[].options[].fare_options[].adult.baggageobjectwhen the airline states itusefulAllowance included in the fare: hand and checkin, each {kg} and/or {pieces}. Absent = not stated.
results[].options[].fare_options[].fare_rulesobjectwhen a rule is known at searchusefulJourney index → id in the top-level fare_rules. A missing index has no rule known at search; the reprice reply carries the final rules.
results[].options[].fare_options[].varies_by_segmentbooleanalwaysinformationaltrue when a later flight of this fare differs from the first in cabin, meal, booking class, fare basis or baggage. Ask detail=segment to see them per flight.
Total: 16 keys
Errors this call answers with (3)
HTTPcodemessagedetailwhen
4019001Authentication requiredInvalid tokenMissing, expired or foreign token; also when the API cannot be reached.
4005100Invalid search requestcabin_class must be 1 (economy), 2 (premium), 3 (business), or 4 (first)errors[] has field cabin_class, rule one_of. Same for fare_types and the engine's own checks (dates, airport codes, pax counts).
5009000Something went wrong
Questions developers ask (4)
What do I send to reprice for a domestic return?
Two items: one option and one fare from group [0] (onward) and one from group [1] (return). An international return has one group [0, 1] and one item.
Why does commission not appear on my fares?
Zero amounts are left out. commission appears only when a commission rule applies to your account; net_fare is then total_fare less it.
How long can I use an option_id and price_id?
Until valid_till of the search reply. After it, search again.
What does varies_by_segment true mean?
A later flight of the fare differs from the first in cabin, meal, booking class, fare basis or baggage. Send detail=segment to see every flight.
Real captures of this call
← POST /generate-tokenPOST /flights/reprice →