POST /api/v1/flights/flexible_search

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

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

Permission: Read

Flexible date search is capability-based. Only suppliers that support flexible-date matrices are queried by this endpoint — currently Amadeus AQC. Suppliers without this capability (e.g. Duffel) are skipped entirely by this endpoint; availability can expand as suppliers are added. Always check for the flexPrices key before reading it — never assume it's present.

This endpoint accepts the same body as get_flights and internally runs the search in flexible-only mode: flexible_only results contain no individual offers, only the date matrix. If you want regular offers and the matrix together in one call, send flexible: true to get_flights directly instead of calling this endpoint.

Request body

Same fields as POST /api/v1/get_flights. Omit supplier_id to query all enabled suppliers that support flexible-date matrices, or target a supplier only after confirming that capability via Suppliers.

One-way: 7-day matrix

curl --request POST \
  --url https://api.fx-port.com/api/v1/flights/flexible_search \
  --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 }
  }'

For a one-way request, matrix has 7 entries — one per day from departure_date - 3 to departure_date + 3 — each keyed only by departure:

{
  "success": true,
  "requestId": "255cfb4d",
  "searchType": "ONE_WAY",
  "flexible": true,
  "suppliers": [
    {
      "success": true,
      "searchId": "fs_amadeus_...",
      "meta": {
        "supplierId": "amadeus_aqc_dz_1",
        "supplierName": "Amadeus Algeria",
        "supportHold": true,
        "supportVoid": true
      },
      "flexPrices": {
        "supplierCurrency": "DZD",
        "agencyCurrency": "DZD",
        "matrix": [
          { "departure": "2026-09-12", "status": "no_flights_available", "finalPrice": null, "basePrice": null, "taxesAndFees": null, "agencyCommission": null },
          { "departure": "2026-09-13", "status": "available", "finalPrice": 27100.00, "basePrice": 18400.0, "taxesAndFees": 8500.0, "agencyCommission": 200.0, "agencyCurrency": "DZD" },
          { "departure": "2026-09-14", "status": "available", "finalPrice": 26500.00, "basePrice": 18000.0, "taxesAndFees": 8300.0, "agencyCommission": 200.0, "agencyCurrency": "DZD" },
          { "departure": "2026-09-15", "status": "available", "finalPrice": 28526.17, "basePrice": 18800.0, "taxesAndFees": 9526.17, "agencyCommission": 200.0, "agencyCurrency": "DZD" },
          { "departure": "2026-09-16", "status": "no_flights_available", "finalPrice": null, "basePrice": null, "taxesAndFees": null, "agencyCommission": null },
          { "departure": "2026-09-17", "status": "no_flights_available", "finalPrice": null, "basePrice": null, "taxesAndFees": null, "agencyCommission": null },
          { "departure": "2026-09-18", "status": "no_flights_available", "finalPrice": null, "basePrice": null, "taxesAndFees": null, "agencyCommission": null }
        ]
      }
    }
  ]
}

Round trip: 7×7 grid

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

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

{
  "flexPrices": {
    "supplierCurrency": "DZD",
    "agencyCurrency": "DZD",
    "matrix": [
      { "departure": "2026-09-12", "return": "2026-09-19", "status": "no_flights_available", "finalPrice": null },
      { "departure": "2026-09-15", "return": "2026-09-22", "status": "available", "finalPrice": 46200.00, "basePrice": 31200.0, "taxesAndFees": 14800.0, "agencyCommission": 200.0, "agencyCurrency": "DZD" },
      { "departure": "2026-09-16", "return": "2026-09-21", "status": "available", "finalPrice": 44950.00, "basePrice": 30500.0, "taxesAndFees": 14250.0, "agencyCommission": 200.0, "agencyCurrency": "DZD" }
    ]
  }
}

`flexPrices` field reference

Field	Type	Meaning
`supplierCurrency` / `agencyCurrency`	string	Currencies for every price in `matrix`
`matrix`	array	One entry per date (one-way) or date pair (round trip / open-jaw) — see below

`matrix[n]` field reference

Field	Type	Meaning
`departure`	string	Candidate departure date, `YYYY-MM-DD`
`return`	string	Candidate return date, `YYYY-MM-DD` — only present for round trip / open-jaw
`status`	string	`available` if the supplier had a fare for this date (combination), otherwise `no_flights_available`
`finalPrice`	number \| null	What the traveler pays for this date, in `agencyCurrency`. `null` when `status` is `no_flights_available`
`basePrice`	number \| null	Base fare before taxes/fees, in `agencyCurrency`
`taxesAndFees`	number \| null	Taxes and platform fees, in `agencyCurrency`
`agencyCommission`	number \| null	Your commission included in `finalPrice`

Every date (or date pair) in the ±3-day window is always present in matrix, even when no fare was found — filter on status === "available" before reading prices, and expect null price fields on no_flights_available entries rather than treating their absence as an error.

Using a matrix result

flexPrices entries do not include a bookable offer ID. To book a specific date from the matrix, run a normal search for that exact departure/return date, then continue with the regular price → book flow.