Adopting Multi-Step Search

Overview

Multi-step search allows integrators to easily implement a flow that involves a traveller selecting one slice of their flight at a time as they build their whole flight itinerary. This enhances the search experience as the whole flow feels faster and intuitive.

There will be significantly fewer offers returned overall, and at each stage. As an integrator with Duffel, this would simplify your job to process and display these offers and will aid the traveller in making a selection from the offers presented to them.

How the flow works?

The multi-step search flow involves more steps but it is intuitive and followed commonly in industry.

Here’s an example flow for a return flight, but you can use this flow for one way or multi-city searches as well.

Outbound search: You pass the origin and destination slices and passengers and get back a list of partial offers for the outbound slice of your journey by creating a partial offer request. A partial offer is an offer that can’t be booked directly but can be passed to the next endpoint: show partial offer request. A partial offer contains only one slice, even if the search is for multiple slices. At the end of the flow (at fare selection), you pass in the partial offers for each of the slices in your journey to obtain a full offer that you can book.
Inbound search: You pass in the offer from the previous outbound search into the endpoint for the inbound search. This will be through the partial offer request show endpoint. You’ll get back partial offers for the next slice of your journey.
Fare selection: You pass in the chosen partial offers obtained from the outbound and inbound search, to obtain a list of full offers. This will be through the fares endpoint.
Create order: Finally you make a booking by passing in the full offer ID obtained at fare selection while creating an order.

Outbound Search

Request

The request parameters are the same as for creating an offer request, except there is no return_offers option as offers are always returned from this flow.

Shell
curl -X POST --compressed "https://api.duffel.com/air/partial_offer_requests"
  -H "Accept-Encoding: gzip"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Duffel-Version: v1"
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"
  -d '{
  "data": {
    "slices": [
      {
        "origin": "LHR",
        "destination": "JFK",
        "departure_date": "2023-12-24"
      },
      {
        "origin": "JFK",
        "destination": "LHR",
        "departure_date": "2023-12-24"
      }
    ],
    "passengers": [
      {
        "type": "adult"
      }
    ]
  }
}'

Response

The response is the same as after creating an offer request, except:

The ID is an identifier for a partial offer request, not an offer request.
The offers returned are partial offers, not full offers. Each partial offer is the cheapest offer available for that itinerary and airline. You will see the field partial set to true for these.

JSON
{
  "id": "prq_00009hthhsUZ8W4LxQghdf",
  // [...]
  "offers": [
    {
      // [...]
      "id": "off_00009htYpSCXrwaB9DnUm0_0",
      "partial": true,
      "slices": [
        /* only one slice outbound */
      ]
    }
  ]
}

Inbound Search

Request

The ID of the partial offer that was selected in the outbound step is sent as a query param named `selected_partial_offer[]

Shell
curl -X GET --compressed
    "https://api.duffel.com/air/partial_offer_requests/$PARTIAL_OFFER_REQUEST_ID_FROM_OUTBOUND_SEARCH?selected_partial_offer[]=$PARTIAL_OFFER_ID_FROM_OUTBOUND_SEARCH"
  -H "Accept-Encoding: gzip"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Duffel-Version: v1"
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"

tip

For Multi-city searches in order to fetch the partial offers for the third slice of the itinerary, selected partial offers need to be provided for both previous slices.

Response

This will return all inbound slices that are valid to be used with the selected_partial_offer[] that were passed in.

JSON
{
  "id": "prq_00009hthhsUZ8W4LxQghdf",
  // [...]
  "offers": [
    {
      // [...]
      "id": "off_00009htYpSCXr3waB9PdIn1_1",
      "partial": true
    }
  ]
}

Fare Selection

Request

The ID of the partial offers that were selected in the outbound and inbound step is sent as a query param named selected_partial_offer[]

Shell
curl -X GET --compressed
    "https://api.duffel.com/air/partial_offer_requests/$PARTIAL_OFFER_REQUEST_ID_FROM_OUTBOUND_SEARCH/fares?selected_partial_offer[]=$PARTIAL_OFFER_ID_FROM_OUTBOUND_SEARCH&selected_partial_offer[]=$PARTIAL_OFFER_ID_FROM_INBOUND_SEARCH"
  -H "Accept-Encoding: gzip"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Duffel-Version: v1"
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN"

tip

For Multi-city searches selected partial offers need to be provided for all slices of the itinerary.

Response

The offers returned at this stage are going to be all full offers that match that itinerary. This is combination of fare and carrier that we have available for the itinerary chosen in the previous step. You will see the field partial set to false for these. You will finally select one of the offer IDs from here as your offer to create an order.

JSON
{
  // [...]
  "offers": [
    {
      // [...]
      "id": "off_00009htYpSCXrwaB9NaDt2",
      "partial": false
    }
  ]
}

Keep Learning

This is how you use multi-step search for booking. Note that if you request offers after they have expired, you won’t get any offers back, even if the search previously yielded offers. For complete API reference regarding this search flow and subsequent order creation you can go to: