Skip to content
FX-Port/Docs
GuidesAPI referenceChangelog
Get API keys
  • Introduction
  • Quickstart
  • Security
  • Authentication
  • Environments and Postman
  • Sandbox
  • Conventions and naming
  • Legacy names and twins
  • Errors
  • Rate limits and fair use
  • Streaming search results

Concepts

  • Overview
  • Booking flows
  • Passengers and ages
  • Pricing
  • Post-booking operations

Search and price

  • Airport autocomplete
  • Search flights
  • Basic routes
  • Passengers and cabins
  • Filters
  • Supplier selection
  • Open-jaw and multi-city
  • Flexible dates
  • Price an offer

Book, pay and cancel

  • Book
  • Quote a held booking
  • Pay a held booking
  • Cancel a held booking
  • Quote a cancellation
  • Confirm a cancellation

After booking

  • Get a booking
  • Get the ticket PDF
  • Get the ticket number
  • ACD passport uploads
  • Use these docs with AI

Flights · Search and price

Flexible-date search

A ±3-day price matrix from suppliers that support flexible-date searches, for both one-way and round-trip requests.

POST/api/v1/flights/flexible_search

Returns a date matrix with the lowest price for each day, ±3 days around the requested departure (and return) date, instead of individual offers.

Permission: Read. Rate group: search.

Flexible-date search is capability-based. Only suppliers that support date matrices are called: today that is Amadeus Algeria (amadeus_aqc_dz_1). Duffel is skipped entirely. Always check that flexPrices is present before you read it.

The endpoint takes the same body as get_flights and runs the search in matrix-only mode: there are no offers in the response, only the matrix. To get the regular offers and the matrix in one call, send "flexible": true to get_flights instead.

Request body

Every field of Search flights applies, with these rules:

  • flexible and flexible_only are set for you.
  • Only suppliers with the flexible-dates capability are called. "supplier_id": "duffel_1" is answered with 400 invalid_supplier_selection and unsupportedFlexibleSuppliers: ["duffel_1"].
  • A route that no flexible-capable supplier serves (for example LHR to CDG, outside Algeria) answers 422 no_supplier_supports_flexible_search (errors[0].field is flexible_only). Use get_flights for fixed dates on that route.
  • The matrix follows the route: a one-way search gives 7 dates, a round trip or an open-jaw gives the combinations of two windows.
  • Identical flexible searches that arrive at the same moment from the same agency, environment and currency are merged into one supplier fan-out. Nothing is kept afterwards, and every caller still gets its own requestId and headers.

One-way: 7 dates

curl https://api.fx-port.com/api/v1/flights/flexible_search \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": "ALG",
  "destination": "CDG",
  "departure_date": "2026-12-15",
  "cabin_class": "economy",
  "passengers": {
    "adults": 1
  }
}'

For a one-way request matrix has 7 entries, one per day from departure_date - 3 to departure_date + 3, each keyed by departure only. Real response (the matrix is shortened to three of the seven entries):

{
  "environment": "sandbox",
  "success": true,
  "requestId": "9c844468",
  "searchType": "ONE_WAY",
  "flexible": true,
  "processingTime": 4.092,
  "flexibleOnly": true,
  "suppliers": [
    {
      "success": true,
      "searchId": "fs_4f72482f-0d24-4aba-882d-d4eb49f6d034",
      "supportHold": true,
      "supportVoid": true,
      "voidDeadline": "2026-11-01T23:00:00Z",
      "filtersApplied": { "flexible": true, "flexibleOnly": true },
      "warnings": [],
      "meta": {
        "supplierId": "amadeus_aqc_dz_1",
        "technologyType": "amadeus_aqc",
        "supplierName": "Amadeus Algeria",
        "processingTime": 4.029,
        "supplierCurrency": "DZD",
        "agencyCurrency": "DZD"
      },
      "flexPrices": {
        "supplierCurrency": "DZD",
        "agencyCurrency": "DZD",
        "matrix": [
          {
            "departure": "2026-12-12",
            "status": "available",
            "finalPrice": 26925.47,
            "basePrice": 18360.0,
            "taxesAndFees": 8538.57,
            "agencyCommission": 26.9,
            "flight": {
              "carrierCode": "IB",
              "flightNumber": "IB1378",
              "operatingCarrier": "IB",
              "validatingAirline": "IB",
              "duration": "PT19H20M",
              "stops": 1,
              "departureTime": "14:05",
              "arrivalTime": "09:25",
              "departureAirport": "ALG",
              "arrivalAirport": "CDG",
              "cabinClass": "ECONOMY",
              "brandedFare": null,
              "brandedFareLabel": null,
              "includedCheckedBags": { "quantity": 1 }
            },
            "b2bPrice": 26898.57,
            "agencyCurrency": "DZD"
          },
          { "departure": "2026-12-13", "status": "available", "finalPrice": 29638.41, "...": "..." },
          { "departure": "2026-12-14", "status": "available", "finalPrice": 29638.41, "...": "..." }
        ]
      }
    }
  ],
  "summary": { "totalSuppliers": 1, "successfulSuppliers": 1, "failedSuppliers": 0, "totalOffers": 0 }
}

summary.totalOffers is 0 and the supplier entry has no results: the answer is the matrix.

Round trip: up to 49 combinations

curl https://api.fx-port.com/api/v1/flights/flexible_search \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": "ALG",
  "destination": "CDG",
  "departure_date": "2026-12-15",
  "return_date": "2026-12-22",
  "cabin_class": "economy",
  "passengers": {
    "adults": 1
  }
}'

For a round trip (or an open-jaw) matrix covers every combination of the two ±3-day windows: 49 entries (7 × 7), each keyed by both departure and return:

{
  "flexPrices": {
    "supplierCurrency": "DZD",
    "agencyCurrency": "DZD",
    "matrix": [
      {
        "departure": "2026-12-12",
        "return": "2026-12-19",
        "status": "available",
        "finalPrice": 36443.69,
        "basePrice": 8470.0,
        "taxesAndFees": 27937.28,
        "agencyCommission": 36.41,
        "flight": { "carrierCode": "AH", "flightNumber": "AH1230", "stops": 0, "departureTime": "18:45", "arrivalTime": "21:15", "...": "..." },
        "b2bPrice": 36407.28,
        "agencyCurrency": "DZD"
      },
      { "departure": "2026-12-12", "return": "2026-12-20", "status": "available", "finalPrice": 36443.69, "...": "..." }
    ]
  }
}

flexPrices fields

FieldTypeMeaning
supplierCurrency, agencyCurrencystringThe currencies of the prices in matrix.
matrixarrayOne entry per date (one-way) or date pair (round trip, open-jaw).

matrix[n] fields

FieldTypeMeaning
departurestringCandidate departure date, YYYY-MM-DD.
returnstringCandidate return date. Only for a round trip or an open-jaw.
statusstringavailable when the supplier has a fare for this date or pair, no_flights_available otherwise.
finalPricenumber or nullWhat the traveler pays, in agencyCurrency.
basePrice, taxesAndFees, agencyCommission, b2bPricenumber or nullThe pricing fields of Flight pricing.
agencyCurrencystringCurrency of the prices of the entry.
flightobjectThe cheapest flight behind the price: carrierCode, flightNumber (with the carrier code: IB1378, unlike offers), operatingCarrier, validatingAirline (a string, unlike the object list of offers), duration, stops, departureTime and arrivalTime (HH:MM), departureAirport, arrivalAirport, cabinClass, brandedFare, brandedFareLabel, includedCheckedBags.quantity.

The matrix is a price calendar: one cheapest fare per date. Entries with status: "no_flights_available" are expected (the price fields are null); filter on available before you read prices.

Book a date from the matrix

An entry has no offer id. To book a date, run a normal search for that exact departure (and return) date, then price and book as usual. The fare of the matrix is an indication: the search can return a different price.

Streaming

With "flexible": true on get_flights?stream=true the matrix arrives with the second, slower batch of Amadeus Algeria: see Streaming search results.

Errors

The errors of Search flights apply. Two are specific to this endpoint:

StatusCodeWhenWhat to do
400invalid_supplier_selectionsupplier_id names a supplier without the flexible-dates capability (unsupportedFlexibleSuppliers lists it).Remove supplier_id, or use amadeus_aqc_dz_1.
422no_supplier_supports_flexible_searchNo supplier can serve a flexible search for this route (outside Algeria).Use get_flights for fixed dates.

The 503 answers of a search apply too: all_suppliers_failed, and supplier_busy or service_overloaded with Retry-After when FX-Port lacked the capacity for a moment. Retry with backoff.

Related

  • Search flights and Filter examples.
  • API reference: Flexible-date search.
PreviousOpen-jaw and multi-city searchesNext Price a flight offer

On this page

  • Request body
  • One-way: 7 dates
  • Round trip: up to 49 combinations
  • flexPrices fields
  • matrix[n] fields
  • Book a date from the matrix
  • Streaming
  • Errors
  • Related

© 2026 FX-Port

TermsPrivacy[email protected]