B2B Flight Booking API (1.0.0)

Searches airports by code, name, city or country. No authentication is required.

Typical use: send what the user typed as q and show the hits. Use IATA_CODE (also returned as code) in Search Flights.

filter examples:

• by country: country_code = "EG"
• by airport code: IATA_CODE = "CAI"

Searches all airlines and suppliers enabled for your agency and returns every bookable offer for the requested route, dates and passengers. Supports one-way (O), round-trip (R) and multi-city (M) searches.

Search modes

Set mode in the request:

• search (default): the response arrives once every supplier has answered, with the full results.
• poll: the response arrives immediately with the search_id and no results yet. Call Collect Results with that search_id every 2-3 seconds; each call returns everything found so far (not just the new results), so replace what you show each time. Stop when status is completed (at the latest about 60 seconds after the search).

Search (mode: poll) ──▶ search_id, status: progress
        │
        ▼
Collect Results ──▶ status: progress ──▶ show results, wait 2-3 s, call again
        │
        └──────────▶ status: completed ──▶ final results, stop polling

Polling shows the first results within seconds instead of waiting for the slowest supplier.

Filters

Narrow the results with the optional filters object:

• direct_only: true returns only non-stop itineraries (every trip is a single flight).
• airlines: ["SV", "MS"] returns only itineraries operated entirely by those airlines.

Filters are applied to every supplier's results. Combine them as needed, e.g. direct flights on one airline.

How the response is organized

The response is split into itineraries (the offers you show and sell) and aggregations (shared reference data). To keep the payload small, an itinerary does not repeat flight or rule details. It lists their ids, and you look them up in aggregations.

Search response
├── search_id ─────────────────────► pass as {search_id} to every next call
│
├── itineraries[]                    one bookable offer each
│   ├── id ────────────────────────► pass as {itinerary_id} to every next call
│   ├── prices                       total for all passengers
│   ├── passengers[]                 price per passenger type
│   ├── trips[]                      one per direction / leg
│   │   └── flights[] ──── ids ───┐
│   ├── rules[] ────────── ids ───┼──┐
│   ├── has_fare_families         │  │  true → call Get Fare Families
│   └── can_hold                  │  │  true → Hold Booking is allowed
│                                 │  │
└── aggregations                  │  │  reference data shared by all itineraries
    ├── flights[]   ◄─────────────┘  │  segment details, find by `id`
    ├── rules{}     ◄────────────────┘  mini fare rules, keyed by id
    ├── passengers[]                    passenger types in this search
    ├── taxes[]                         tax lines (supplier dependent)
    ├── fares[]                         fare components (supplier dependent)
    └── translations                    airport and airline names

Itineraries

Each itinerary is one priced, bookable combination of flights.

• prices is the total for all passengers. passengers[].prices is the price for one passenger of that type.
• trips holds one entry per direction: 1 for one-way, 2 for round-trip, one per leg for multi-city. Each trip lists its flight segments in travel order, so a trip with several flight ids has connections.
• Prices are in the requested currency and already include your agency markup.

Aggregations

• flights: one entry per flight segment (airports, times, carriers, flight number, cabin, booking class, baggage, fare family amenities). A segment shared by several itineraries appears only once.
  • bags_per_pax is the baggage breakdown per passenger type (adult, child, infant), each with check_in and cabin allowance.
  • free_baggage and cabin_baggage are short codes for the adult (ADT) allowance only.
• rules: mini fare rules, a short summary of refund/change conditions (type is REFUND, CHANGE, REVALIDATE, ...) for showing badges such as "Refundable" in results. Several itineraries can point to the same rule. When the airline gives no detail, the rule says to contact support. For the full conditions of one itinerary, call Get Fare Rules.
• passengers: the passenger types of the search (ADT, CHI, INF).
• taxes and fares: tax lines and fare components. They depend on the supplier and may be empty; don't rely on them being present.
• translations: airport and airline names keyed by code, in the requested locale.

Next steps

1. If has_fare_families is true, optionally call Get Fare Families to offer branded fares.
2. Optionally call Get Fare Rules for the full conditions.
3. Call Check Availability before booking to confirm the price.

Returns the results of a search made with mode: poll. Call it every 2-3 seconds with the search_id of the search.

Each call returns all results found so far, in the same structure as the Search response, so replace what you show each time. Keep calling while status is progress; stop when it is completed.

This step is optional. If the itinerary has has_fare_family set to true, you can use it to fetch the branded fare offers.

Confirms that the selected itinerary is still available, re-prices it, and returns the full details of the trip that will be booked. Call it before Create Order.

If you intend to book a specific branded fare (fare family), pass the corresponding fare_family_id.

Use the availability response, not the search result

The flights in order_details.data.flights are the trip that will actually be booked. Baggage (bags_per_pax, free_baggage), fare basis (fare_base), fare type, booking class and branded fare can differ from what Search returned, so replace the flight details you show with these before Create Order; don't rely on the search result.

Also check price_changed / price_change: if the price changed, show the new price to the customer before continuing.

Returns the fare rules (cancellation, change and no-show conditions) for a selected itinerary.

This step is optional and informational — it does not affect pricing or booking. It can be called any time after search, within the same search session.

If the customer selected a branded fare (fare family), pass the same fare_family_id you use for Check Availability, so the returned rules match that fare.

If no rules are available for the itinerary, rules is an empty object and text is null.

Creates the order for the selected itinerary and saves the passengers and contact details.

This endpoint does not book with the airline. It doesn't create a PNR, take payment or issue tickets; it only saves the order so you can continue with one of the next steps:

• Hold Booking: creates the PNR without payment (only when the itinerary allows hold), then pay later with Pay and Issue Ticket.
• Pay and Issue Ticket: pays from your agency balance, creates the PNR and issues the tickets.

Call Check Availability before this endpoint to confirm the price.

This endpoint retrieves comprehensive details of a specific flight booking, including:

• Passenger information.
• PNR (Passenger Name Record).
• Tickets.
• Booking status.

Usage Instructions:

• Call this endpoint every 10 minutes for up to 2 hours after the booking is created.
• Check for the generation of PNR and tickets during this time-frame.

Timeout Behavior:

• If neither the PNR nor tickets are generated within 2 hours, the booking is considered unconfirmed.
• In such cases, contact the supplier directly to verify the final booking status.

Example Workflow:

1. Create a flight booking.
2. Poll this endpoint every 10 minutes for updates.
3. If the booking remains unconfirmed after 2 hours, escalate to the supplier for resolution.

This ensures timely and accurate updates to the booking status while minimizing manual intervention.

Baggage

Baggage breakdown per passenger type (adult, child, infant), each with check_in and cabin allowance. Use this for the exact allowance of every passenger. free_baggage and cabin_baggage on the flight are short codes for the adult (ADT) allowance only.

Available actions

order.available_actions lists what you can do on the booking now. Currently only void, and only when the ticket can be voided through the API; see Void Ticket.