Skip to Content
OpenRoam Docs
Flights

Search flights

Searches flight itineraries and the fares bookable on them.

POST
/v1/flights/search

Searches flight itineraries and the fares bookable on them.

Send one slice per flight (one for one-way, two for a return, more for a multi-city trip) and every passenger; at least one passenger must be an adult, and children and infants need an age. Optional filters: maxStops, preferredAirlines and excludedAirlines select itineraries; refundableOnly and maxPrice select fares, and an itinerary left without a fare is not returned. The body rejects an unknown field at every level, and the route takes no query parameters.

Returns { items, pagination }. Each item is one itinerary, the same flights sold by the same airline, with its fares as offers, cheapest first; items are ordered by their cheapest fare, then total duration. page and limit (defaults 1 and 10, limit at most 100) page through itineraries, and pagination.totalCount counts them. Each page runs a new airline search, so fares can change between pages.

An item's id is valid only within this response and cannot be ordered; quote and order an offer's publicId before its details.expiresAt. Prices are for all passengers, in currency or the API key's currency, and are indicative.

Errors: an invalid or unknown field, or a query parameter, 400 / 10001; an unsupported currency 404 / 10004.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Request Body

  1. body

Flight search body: the trip, the passengers, optional filters, the page of itineraries and an optional price currency. Unknown fields are rejected at every level.

slices*array<>

One entry per flight of the trip: one for one-way, two for a return, more for a multi-city trip. At least one.

passengers*array<>

One entry per traveller; at least one must be an adult.

cabinClass?|

Cabin to search: economy, premiumEconomy, business or first. Optional.

Value in"economy""premiumEconomy""business""first"
filters?|

Optional filters. maxStops, preferredAirlines and excludedAirlines select itineraries; refundableOnly and maxPrice select fares, and an itinerary left without a fare is not returned.

page?integer

Page of itineraries, from 1; default 1.

Formatint32
limit?integer

Itineraries per page, 1 to 100; default 10.

Formatint32
currency?|

Three-letter ISO 4217 price currency, in either case; the API key's currency when omitted or blank. An unsupported code gives 404 / 10004.

Response Body

OK

  1. response

A page of itineraries. pagination.totalCount counts the itineraries with at least one fare after the filters. Each page runs a new airline search, so offers can change between pages.

items*array<>
pagination*

Paging of a list response.

Example Request
curl -X POST 'https://api.sandbox.openroam.com/v1/flights/search' \  -H 'Content-Type: application/json' \  -d '{  "currency": "USD",  "slices": [    {      "origin": "LHR",      "destination": "JFK",      "departureDate": "2026-12-12"    },    {      "origin": "JFK",      "destination": "LHR",      "departureDate": "2026-12-19"    }  ],  "passengers": [    {      "type": "adult"    },    {      "type": "child",      "age": 7    }  ],  "cabinClass": "economy",  "filters": {    "maxStops": 1,    "preferredAirlines": [      "BA"    ],    "refundableOnly": false,    "maxPrice": 1500  },  "page": 1,  "limit": 10}'
Example Response
{  "items": [    {      "id": "string",      "name": "string",      "countryCode": "string",      "category": "string",      "logoUrl": "string",      "description": "string",      "offers": [        {          "publicId": "string",          "name": "string",          "description": "string",          "price": {            "amount": 0,            "currency": "string"          },          "details": {            "expiresAt": "2019-08-24T14:15:22Z",            "cabinClass": "economy",            "fare": {              "fareBasisCode": "string",              "brandName": "string",              "fareFamily": "string",              "validatingCarrier": "string"            },            "terms": {              "payment": {                "type": "payNow",                "dueNow": {                  "amount": 0,                  "currency": "string"                },                "dueLater": {                  "amount": 0,                  "currency": "string"                },                "dueLaterAt": "property"              },              "cancellation": {                "type": "fullyRefundable",                "freeUntil": "2019-08-24T14:15:22Z",                "freeUntilLocalTime": "2026-12-01T08:30:00",                "timezone": "string",                "schedule": [                  {                    "from": "2019-08-24T14:15:22Z",                    "fromLocalTime": "2026-12-01T08:30:00",                    "refund": {                      "amount": 0,                      "currency": "string"                    },                    "penalty": {                      "amount": 0,                      "currency": "string"                    }                  }                ],                "fee": {                  "amount": 0,                  "currency": "string"                }              },              "changes": {                "allowed": true,                "fee": {                  "type": "fixed",                  "amount": {                    "amount": 0,                    "currency": "string"                  },                  "percent": 0,                  "min": {                    "amount": 0,                    "currency": "string"                  },                  "max": {                    "amount": 0,                    "currency": "string"                  }                }              }            },            "includedBaggage": [              {                "type": "unknown",                "quantity": 0,                "weightKg": 0,                "description": "string"              }            ],            "priceBreakdown": {              "base": {                "amount": 0,                "currency": "string"              },              "tax": {                "amount": 0,                "currency": "string"              }            },            "passengerPricing": [              {                "passengerType": "adult",                "count": 0,                "pricePerPassenger": {                  "amount": 0,                  "currency": "string"                },                "priceBreakdown": {                  "base": {                    "amount": 0,                    "currency": "string"                  },                  "tax": {                    "amount": 0,                    "currency": "string"                  }                },                "fareBasisCode": "string",                "bookingClass": "string"              }            ],            "offerPassengers": [              {                "passengerIndex": 0,                "type": "adult",                "age": 0,                "fareType": "string",                "includedBaggage": [                  {                    "type": "unknown",                    "quantity": 0,                    "weightKg": 0,                    "description": "string"                  }                ],                "availableServices": [                  {                    "id": "string",                    "type": "string",                    "price": {                      "amount": 0,                      "currency": "string"                    },                    "passengerIndexes": [                      0                    ],                    "segments": [                      {                        "sliceIndex": 0,                        "segmentIndex": 0                      }                    ],                    "maxQuantity": 0,                    "baggage": {                      "type": "string",                      "maximumWeightKg": 0,                      "maximumLengthCm": 0,                      "maximumHeightCm": 0,                      "maximumDepthCm": 0                    }                  }                ]              }            ],            "availableServices": [              {                "id": "string",                "type": "string",                "price": {                  "amount": 0,                  "currency": "string"                },                "passengerIndexes": [                  0                ],                "segments": [                  {                    "sliceIndex": 0,                    "segmentIndex": 0                  }                ],                "maxQuantity": 0,                "baggage": {                  "type": "string",                  "maximumWeightKg": 0,                  "maximumLengthCm": 0,                  "maximumHeightCm": 0,                  "maximumDepthCm": 0                }              }            ],            "identityDocumentsRequired": true,            "supportedDocumentTypes": [              "string"            ],            "segments": [              {                "sliceIndex": 0,                "segmentIndex": 0,                "cabinClass": "economy",                "baggage": [                  {                    "type": "unknown",                    "quantity": 0,                    "weightKg": 0,                    "description": "string"                  }                ]              }            ]          }        }      ],      "details": {        "owner": {          "iataCode": "string",          "name": "string",          "logoUrl": "string"        },        "slices": [          {            "origin": {              "iataCode": "string",              "icaoCode": "string",              "name": "string",              "city": "string",              "cityIataCode": "string",              "countryCode": "string",              "terminal": "string",              "timezone": "string"            },            "destination": {              "iataCode": "string",              "icaoCode": "string",              "name": "string",              "city": "string",              "cityIataCode": "string",              "countryCode": "string",              "terminal": "string",              "timezone": "string"            },            "departureAt": "2019-08-24T14:15:22Z",            "departureLocalTime": "2026-12-01T08:30:00",            "arrivalAt": "2019-08-24T14:15:22Z",            "arrivalLocalTime": "2026-12-01T08:30:00",            "durationMinutes": 0,            "stops": 0,            "segments": [              {                "origin": {                  "iataCode": "string",                  "icaoCode": "string",                  "name": "string",                  "city": "string",                  "cityIataCode": "string",                  "countryCode": "string",                  "terminal": "string",                  "timezone": "string"                },                "destination": {                  "iataCode": "string",                  "icaoCode": "string",                  "name": "string",                  "city": "string",                  "cityIataCode": "string",                  "countryCode": "string",                  "terminal": "string",                  "timezone": "string"                },                "departureAt": "2019-08-24T14:15:22Z",                "departureLocalTime": "2026-12-01T08:30:00",                "arrivalAt": "2019-08-24T14:15:22Z",                "arrivalLocalTime": "2026-12-01T08:30:00",                "durationMinutes": 0,                "marketingCarrier": {                  "iataCode": "string",                  "name": "string",                  "logoUrl": "string"                },                "marketingFlightNumber": "string",                "operatingCarrier": {                  "iataCode": "string",                  "name": "string",                  "logoUrl": "string"                },                "operatingFlightNumber": "string",                "aircraft": {                  "iataCode": "string",                  "name": "string",                  "imageUrl": "string"                },                "stops": [                  {                    "airport": {                      "iataCode": "string",                      "icaoCode": "string",                      "name": "string",                      "city": "string",                      "cityIataCode": "string",                      "countryCode": "string",                      "terminal": "string",                      "timezone": "string"                    },                    "arrivingAt": "2019-08-24T14:15:22Z",                    "arrivingLocalTime": "2026-12-01T08:30:00",                    "departingAt": "2019-08-24T14:15:22Z",                    "departingLocalTime": "2026-12-01T08:30:00",                    "durationMinutes": 0                  }                ],                "isCodeshare": true              }            ]          }        ],        "marketingCarriers": [          {            "iataCode": "string",            "name": "string",            "logoUrl": "string"          }        ],        "operatingCarriers": [          {            "iataCode": "string",            "name": "string",            "logoUrl": "string"          }        ],        "totalDurationMinutes": 0,        "totalStops": 0,        "totalEmissionsKg": 0      }    }  ],  "pagination": {    "currentCount": 0,    "totalCount": 0,    "skip": 0,    "limit": 0,    "hasMore": true,    "page": 0,    "totalPages": 0  }}

Quote flights POST

Prices flight fares again with the airline, without placing an order. Takes the same body as order: `{ currency, referenceId, items[] }` with 1 to 5 items, each `{ publicId, quantity, inputs }` and `quantity` 1. `inputs` may be left out: the quote then prices the fare alone. Inputs that are sent are checked as the order checks them, and their paid extras are added to the price. Prices are in `currency`, or in the API key's currency when it is omitted. Nothing is charged or held. Returns `{ currency, items, total }`. Each item has a new `publicId`: order with it before `details.expiresAt`. It keeps the fare's price, which caps an order without `inputs.maxPrice`. `details` carries the fare's conditions, included baggage and price breakdown, `hasSeatMaps`, the paid extras (`availableServices`) that can be sent in the order's `inputs.selectedServices`, and `fareOptions`: the fares for the same flights and airline, cheapest first and including the quoted one, each with its own `publicId` that can be quoted or ordered. A higher airline price is returned with 200; only `inputs.maxPrice` stops a quote. Each item is checked completely, its inputs, its `publicId` and its price, before the next one, and the first failure names its item: an invalid input or a `quantity` other than 1 gives 400 / 10001 at its path under `items[i]`; a price above `inputs.maxPrice` 409 / 11002 at `items[i].inputs.maxPrice`; an offer the airline no longer sells 409 / 11003 at `items[i]`; an unknown, expired or another partner's `publicId`, or a search itinerary `id`, 400 / 11004 at `items[i]`. An unsupported `currency` gives 400 / 10001 at `currency`.

esim.profileStatus.updated

Delivered at least once to your webhook URL. Acknowledge with any `2xx` response. A signed body with `isTest: true` contains synthetic data and should be handled as a connectivity check.