Searching and booking flights

Flights follow the standard four-step flow: search → fares → build → book.
Search and fares stream results as Server-Sent Events (SSE); build and book
return JSON. All requests require the consumer HMAC and a traveler bearer
token — omitted from the snippets below for brevity.

1. Look up airports

Resolve free-text input to IATA codes before searching.

GET /v1/flights/airports?q=milan&limit=5

Response — an array of FlightAirportOut:

[
  {
    "iata": "MXP",
    "name": "Milan Malpensa",
    "city": "Milan",
    "country": "IT",
    "timezone": "Europe/Rome",
    "is_metro": false
  }
]

2. Search

POST /v1/flights/search initiates a search and streams normalised solutions
back as SSE. Each data: event is a JSON flight solution whose id is a
canonical Mercury UUID. The stream ends with event: done.

Request body (FlightSearchRequest) — one leg per itinerary entry (two legs for
a round trip):

{
  "itinerary": [
    { "origin": "MXP", "destination": "LHR", "date": "2026-02-10" },
    { "origin": "LHR", "destination": "MXP", "date": "2026-02-14" }
  ],
  "passengers": { "adults": 1, "children": 0, "infants": 0 },
  "cabinClass": "economy",
  "directOnly": false
}

cabinClass is one of economy, premium_economy, business, first.
Optional priceMin / priceMax bound the results. Each FlightLeg also
accepts departureAfter / departureBefore / arrivalAfter / arrivalBefore
as HH:MM local-time windows.

event: solution
data: {"id":"018f...","...":"..."}

event: done
data: {}

Each solution arrives as an event: solution frame; the stream closes with
event: done, and a provider failure ends it with event: error. Keep the
solution id you want to fare — it is the searchSolutionId for the next step.

3. List fares

POST /v1/flights/fares streams the bookable fares for a chosen solution as SSE.

Request body (FlightFaresBody):

{ "searchSolutionId": "018f...", "solutionKey": null }

Each streamed fare carries a fareId and solutionKey used to build it.

External fares are withheld by default. Pay-at-airline (external) fares
are not surfaced unless your environment enables them. Fares returned here are
prepaid through BizAway.

4. Build the fare

POST /v1/flights/fares/build locks a specific fare and returns it as JSON
(201).

Request body (FlightBuildFareBody):

{ "fareId": "018f...", "searchSolutionId": "018f...", "solutionKey": null }

Response (FlightFareOut, abbreviated):

{
  "fareId": "018f...",
  "solutionKey": "abc...",
  "providerName": "example-airline",
  "merchant": "bizaway",
  "totalPrice": { "amount": "149.90", "currency": "EUR" },
  "cabinClass": "economy",
  "isRefundable": false,
  "isChangeable": true
}

Money is always { "amount": "149.90", "currency": "EUR" } with the amount as a
string carrying at least two decimals.

5. (Optional) Protection plans

Before booking, list available protection plans for a built fare:

GET /v1/flights/fares/{fare_id}/protection-plans

6. Book

POST /v1/flights/bookings creates the booking from the built fareId. Send a
unique Idempotency-Key header (required — see
Bookings and trips).

Request body (CreateBookingRequest):

{
  "fareId": "018f...",
  "passengers": [
    {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "type": "adult",
      "birthday": "1990-12-10",
      "gender": "F",
      "nationality": "GB",
      "isHolder": true,
      "documentNumber": "P1234567"
    }
  ],
  "isPersonal": false,
  "tripId": null
}

Pass tripId to attach the booking to an existing trip, or leave it out and
associate it later (see Bookings and trips). Manage
the booking lifecycle — confirm, cancel, calculate costs — with the shared
booking endpoints documented in that guide.

See the API Reference for the complete request and
response schemas.

Reporting issues

This page is maintained by the BizAway integration team. To request changes or
report an error, contact your BizAway integration contact. Edits made directly
in the ReadMe dashboard are overwritten on the next publish.