# Flexible-date search

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

Endpoint: `POST /api/v1/flights/flexible_search`

Source: https://fx-port.com/docs/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.


> [!WARNING]
> **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`](https://fx-port.com/docs/flights/search.md) 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](https://fx-port.com/docs/flights/search.md#request-fields) 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`](https://fx-port.com/docs/flights/search.md) 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


**Request**

```bash
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):

~~~json
{
  "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


**Request**

```bash
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`:

~~~json
{
  "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

| Field | Type | Meaning |
|---|---|---|
| `supplierCurrency`, `agencyCurrency` | string | The currencies of the prices in `matrix`. |
| `matrix` | array | One entry per date (one-way) or date pair (round trip, open-jaw). |

## `matrix[n]` fields

| Field | Type | Meaning |
|---|---|---|
| `departure` | string | Candidate departure date, `YYYY-MM-DD`. |
| `return` | string | Candidate return date. **Only** for a round trip or an open-jaw. |
| `status` | string | `available` when the supplier has a fare for this date or pair, `no_flights_available` otherwise. |
| `finalPrice` | number or null | What the traveler pays, in `agencyCurrency`. |
| `basePrice`, `taxesAndFees`, `agencyCommission`, `b2bPrice` | number or null | The pricing fields of [Flight pricing](https://fx-port.com/docs/flights/pricing.md). |
| `agencyCurrency` | string | Currency of the prices of the entry. |
| `flight` | object | The 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](https://fx-port.com/docs/flights/search.md) for that exact `departure` (and `return`) date, then [price](https://fx-port.com/docs/flights/price.md) and [book](https://fx-port.com/docs/flights/book.md) 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](https://fx-port.com/docs/streaming.md#flexible-dates).

## Errors

The errors of [Search flights](https://fx-port.com/docs/flights/search.md#errors) apply. Two are specific to this endpoint:

| Status | Code | When | What to do |
|---|---|---|---|
| `400` | `invalid_supplier_selection` | `supplier_id` names a supplier without the flexible-dates capability (`unsupportedFlexibleSuppliers` lists it). | Remove `supplier_id`, or use `amadeus_aqc_dz_1`. |
| `422` | `no_supplier_supports_flexible_search` | No 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](https://fx-port.com/docs/flights/search.md) and [Filter examples](https://fx-port.com/docs/flights/search/filters.md#flexible-dates-across-all-suppliers).
- [API reference: Flexible-date search](https://fx-port.com/docs/api/flexible-search.md).