POST /api/v1/get_flights

Search for flights across one, several, or every enabled supplier. Start here, then expand the examples by route, passenger, filter, supplier, or itinerary type.

Search available flight offers across one, several, or every enabled supplier. Results are grouped under suppliers[]; each supplier has its own searchId and offer list.

Permission: Read

Save the supplier-level searchId. Pass suppliers[n].searchId to price_flight and book_flight — never the top-level requestId.

Request fields

Route

Field	Type	Required	Description
`origin`	string	Yes¹	Departure IATA code (`ALG`, `CAI`, `LHR`)
`destination`	string	Yes¹	Arrival IATA code
`departure_date`	string	Yes¹	`YYYY-MM-DD`
`return_date`	string	No	Add for a round trip
`segments`	array	No²	Exactly two open-jaw legs: `{ origin, destination, date }`

¹ Simple one-way/round-trip only. ² Use exactly two segments for open-jaw.

Passengers and cabin

Field	Type	Required	Description
`passengers`	object	Yes	Counts and age arrays; see Flight passengers & ages
`cabin_class`	string	No	`economy` (default), `premium_economy`, `business`, `first`, `any`

Filters

Field	Type	Description
`direct`	boolean	`true` → non-stop offers only (alias: `nonstop`)
`refundable`	boolean	`true` → prefer refundable offers; not enforced by every supplier, always confirm on the offer
`checked_bags`	boolean	`true` → offers that include checked baggage
`max_price`	number	Maximum total price in the agency currency; not enforced by every supplier yet — see Filter examples
`included_airlines`	string[]	Restrict results to these IATA carrier codes
`excluded_airlines`	string[]	Remove these IATA carrier codes from the results
`preferred_airlines`	string[]	Alias of `included_airlines` — currently the same strict allow-list behavior, not a soft ranking
`flexible`	boolean	Request flexible dates from capable suppliers; regular offers still return

See Filter examples for the full behavior, caveats, and example responses for each filter.

Supplier selection

Field	Type	Behaviour
(omit selectors)	—	Recommended. FX-Port selects compatible enabled suppliers automatically.
`supplier_id`	string	Advanced: restrict the search to one exact supplier ID.
`supplier_ids`	string[]	Advanced: restrict the search to an exact supplier set.

Usually, omit all supplier fields and let FX-Port manage selection. For the special case “use exactly 2 of our 5 suppliers”, send supplier_ids: ["supplier_a", "supplier_b"]. The backend calls enabled suppliers in parallel. Unknown, disabled, or flexible-incompatible strict selections return HTTP 400. Traveler-incompatible suppliers are skipped silently; HTTP 400 is returned only when no selected supplier remains compatible.

Examples by category

Basic routes

One-way, round-trip, direct-only, and all suppliers.

Passengers & cabins

Family mix, lap/seated infants, senior/young adult, business, premium economy, all cabins.

Filters

Refundable, checked bags, price cap, market hints, include/exclude/preferred airlines, flexible dates.

Supplier selection

Automatic selection (recommended) or exact supplier IDs for special cases.

Open-jaw

Search two non-reversed flight segments.

Minimal request

curl --request POST \
  --url https://api.fx-port.com/api/v1/get_flights \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "origin": "ALG",
    "destination": "CDG",
    "departure_date": "2026-09-15",
    "cabin_class": "economy",
    "passengers": { "adults": 1 }
  }'

Response essentials

The example below is a trimmed real sandbox response for the request above (fields present on every offer are kept; repeated/optional fields are trimmed for length — see the field reference tables underneath for everything not shown).

{
  "success": true,
  "requestId": "255cfb4d",
  "searchType": "ONE_WAY",
  "flexible": false,
  "processingTime": 4.282,
  "suppliers": [
    {
      "success": true,
      "searchId": "fs_dfx_4a861fcd-c5d6-4a1e-a471-97db7a9f9982",
      "supportHold": false,
      "supportVoid": false,
      "voidDeadline": null,
      "meta": {
        "supplierId": "duffel_1",
        "technologyType": "duffel",
        "supplierName": "Duffel",
        "processingTime": 1.792,
        "supplierCurrency": "USD",
        "agencyCurrency": "DZD"
      },
      "results": {
        "totalOffers": 115,
        "supplierCurrency": "USD",
        "agencyCurrency": "DZD",
        "offers": [
          {
            "id": "fx_offer_860f61e3",
            "type": "flight_offer",
            "supplier": { "id": "duffel_1", "name": "Duffel", "originalId": "off_0000B9nxOvvmY4qNUnYSFL" },
            "bookableSeats": null,
            "supportHold": false,
            "supportVoid": false,
            "instantTicketingRequired": false,
            "lastTicketingDate": "2026-08-27",
            "lastTicketingDateTime": "2026-08-27T17:58:25.166703Z",
            "pricing": {
              "supplierCurrency": "USD",
              "agencyCurrency": "DZD",
              "basePrice": 16270.0,
              "taxesAndFees": 5198.2,
              "agencyCommission": 21.47,
              "finalPrice": 21489.67,
              "b2bPrice": 21468.2,
              "additionalServices": []
            },
            "itinerary": [
              {
                "direction": "outbound",
                "duration": "PT2H24M",
                "stops": 0,
                "segments": [
                  {
                    "id": "seg_0000B9nxOvvmY4qNUnYSFA",
                    "departure": {
                      "airportCode": "ALG",
                      "airportName": "Houari Boumediene Airport",
                      "cityName": "Algiers",
                      "countryCode": "DZ",
                      "terminal": "2",
                      "datetime": "2026-09-15T10:50:00",
                      "timeZone": "Africa/Algiers"
                    },
                    "arrival": {
                      "airportCode": "CDG",
                      "airportName": "Paris Charles de Gaulle Airport",
                      "cityName": "Paris",
                      "countryCode": "FR",
                      "terminal": "1",
                      "datetime": "2026-09-15T14:14:00",
                      "timeZone": "Europe/Paris"
                    },
                    "flight": {
                      "carrierCode": "IB",
                      "carrierName": "Iberia",
                      "flightNumber": "3177",
                      "operatingCarrier": "IB",
                      "operatingCarrierName": "Iberia"
                    },
                    "duration": "PT2H24M",
                    "cabin": "ECONOMY",
                    "fareBasis": "Y20LGTN2",
                    "brandedFare": "BASIC",
                    "brandedFareLabel": "Basic"
                  }
                ],
                "conditions": {
                  "changeBeforeDeparture": { "allowed": true },
                  "refundBeforeDeparture": { "allowed": false }
                }
              }
            ],
            "travelerPricing": [
              {
                "travelerId": "pas_0000B9nxOvjNICv2sJkXtl",
                "travelerType": "ADULT",
                "fareOption": "STANDARD",
                "price": {
                  "supplierCurrency": "USD",
                  "agencyCurrency": "DZD",
                  "base": 16270.0,
                  "total": 21489.67,
                  "b2bPrice": 21468.2
                },
                "fareDetailsBySegment": [
                  {
                    "segmentId": "seg_0000B9nxOvvmY4qNUnYSFA",
                    "cabin": "ECONOMY",
                    "fareBasis": "Y20LGTN2",
                    "brandedFare": "BASIC",
                    "brandedFareLabel": "Basic",
                    "includedCheckedBags": { "quantity": 1 },
                    "includedCabinBags": { "quantity": 1 },
                    "amenities": [
                      { "description": "WIFI", "isChargeable": true, "amenityType": "WIFI" }
                    ]
                  }
                ]
              }
            ],
            "conditions": {
              "refundBeforeDeparture": { "allowed": false },
              "changeBeforeDeparture": { "allowed": true }
            },
            "fareRules": {
              "exchange": { "allowed": true },
              "refund": { "allowed": false },
              "revalidation": { "allowed": false }
            },
            "validatingAirline": [{ "code": "IB", "name": "Iberia" }]
          }
        ]
      }
    }
  ]
}

Top-level response fields

Field	Type	Meaning
`success`	boolean	`true` if the search executed (individual suppliers can still fail independently — see `suppliers[n].success`)
`requestId`	string	FX-Port's internal ID for this search call — include it when contacting support
`searchType`	string	`ONE_WAY`, `ROUND_TRIP`, or `OPEN_JAW` (two non-reversed `segments`), derived from your request. Multi-city (3+ segments) is not supported — do not send more than two `segments`
`flexible`	boolean	Whether this search requested the flexible-date matrix (`flexible: true` in the request)
`processingTime`	number	Total time in seconds FX-Port spent calling all suppliers for this request
`suppliers`	array	One entry per supplier that was called — see below

`suppliers[n]` fields

Field	Type	Meaning
`success`	boolean	Whether this specific supplier returned usable results
`searchId`	string	Save this. Required as `search_id` on price_flight and, indirectly, on booking
`supportHold`	boolean	Whether this supplier can create a hold (pay-later) reservation for these offers
`supportVoid`	boolean	Whether this supplier supports same-day void of an issued ticket
`voidDeadline`	string \| null	Next void cutoff (UTC), if `supportVoid` is `true`
`meta.supplierId`	string	Supplier identifier, e.g. `duffel_1` — matches suppliers
`meta.technologyType`	string	Underlying integration technology (`duffel`, `amadeus_aqc`, `ndc`, …)
`meta.supplierName`	string	Human-readable supplier name
`meta.processingTime`	number	Time in seconds this individual supplier took to respond
`meta.supplierCurrency` / `meta.agencyCurrency`	string	Currencies used for conversion — see Flight pricing
`results.totalOffers`	number	Total offers this supplier returned (may exceed what's shown if paginated internally)
`results.offers`	array	The offers themselves — see below

`offers[n]` fields

Field	Type	Meaning
`id`	string	Save this. Required as `offer_id` on price_flight
`type`	string	Always `flight_offer`
`supplier.id` / `supplier.name`	string	Which supplier this specific offer came from
`supplier.originalId`	string	The supplier's own internal offer ID (opaque, for support/debugging only)
`bookableSeats`	number \| null	Remaining bookable seats at this fare, when the supplier reports it
`supportHold` / `supportVoid` / `voidDeadline`	—	Same meaning as at the supplier level, but specific to this offer
`instantTicketingRequired`	boolean	`true` means this fare cannot be held — must book with `booking_type: "issue"`
`lastTicketingDate` / `lastTicketingDateTime`	string	Deadline to issue a ticket for this specific offer
`pricing`	object	See Flight pricing for every field's meaning
`itinerary`	array	One entry per direction (`outbound`, and `return` for round trips) — see below
`travelerPricing`	array	Per-traveler price breakdown — one entry per passenger, see below
`conditions`	object	Offer-level refund/change eligibility (`allowed: true/false`); indicative, not a guarantee
`fareRules`	object	Same refund/exchange eligibility, plus `revalidation`
`validatingAirline`	array	The airline whose fare rules and ticket stock govern this booking

`itinerary[n]` and `segments[n]` fields

Field	Type	Meaning
`direction`	string	`outbound` or `return`
`duration`	string	ISO-8601 duration for this direction, e.g. `PT2H24M` = 2h24m
`stops`	number	Number of stops in this direction (`0` = non-stop)
`segments[n].departure` / `.arrival`	object	`airportCode`, `airportName`, `cityName`, `countryCode`, `terminal`, `datetime` (local), `timeZone`
`segments[n].flight.carrierCode` / `.carrierName`	string	Marketing carrier
`segments[n].flight.operatingCarrier` / `.operatingCarrierName`	string	Operating carrier — differs from marketing carrier on codeshares
`segments[n].flight.flightNumber`	string	Flight number as filed by the carrier
`segments[n].cabin`	string	Cabin for this specific segment (can differ from the requested `cabin_class` on mixed-cabin itineraries)
`segments[n].fareBasis`	string	Fare basis code — supplier/GDS-specific
`segments[n].brandedFare` / `.brandedFareLabel`	string	Fare family code and its display label, when the supplier exposes branded fares
`conditions.changeBeforeDeparture.allowed`	boolean	Whether a change is generally permitted before departure for this direction
`conditions.refundBeforeDeparture.allowed`	boolean	Whether a refund is generally permitted before departure for this direction

`travelerPricing[n]` fields

Field	Type	Meaning
`travelerId`	string	Identifies which passenger (by search order) this price applies to
`travelerType`	string	`ADULT`, `SENIOR`, `YOUNG_ADULT`, `CHILD`, `INFANT`, or `SEATED_INFANT`
`fareOption`	string	Fare option selected for this traveler, e.g. `STANDARD`
`price`	object	This traveler's own share of `base`/`total`/`b2bPrice` — see Flight pricing
`fareDetailsBySegment[n].includedCheckedBags.quantity`	number	Checked bags included for this traveler on this segment
`fareDetailsBySegment[n].includedCabinBags.quantity`	number	Cabin bags included for this traveler on this segment
`fareDetailsBySegment[n].amenities`	array	Optional amenity list (Wi-Fi, seat pitch, entertainment, …); `isChargeable` marks paid extras

Save these values

Value	Location	Used by
`searchId`	`suppliers[n].searchId`	Required `price_flight.search_id`, then booking
offer `id`	`suppliers[n].results.offers[m].id`	Required `price_flight.offer_id`, then booking
`supportHold`	Supplier and priced offer	Use hold only when still `true` after pricing

POST /api/v1/get_flights

Basic routes

Passengers & cabins

Filters

Supplier selection

Open-jaw

On this page