Getting started with flights

This guide will walk you through how to go from nothing to your first booking.

Before you can get started with this guide, you'll need to:

Sign up for a Duffel account (it takes about 1 minute!)
Create a test access token from the "Access tokens" page in your Dashboard

To make it easy to build your Duffel integration, we offer client libraries in JavaScript, Python, Ruby, C# and Java.

Additionally, we also offer a CLI for generating an example flight booking application with Duffel integrated so you can start getting your hands dirty right away.

If you aren't using JavaScript, you can follow along with curl in your terminal, or you can script the flow using your preferred programming language, or you can use the API in an HTTP client like Postman.

tip

We've put together a Postman Collection that contains all of the requests you'll need to follow along with this guide.

Overview

Everything starts with passengers and a journey. In this guide, we'll follow an example scenario:

Tony, Pepper, and their daughter Morgan want to fly from New York City to Atlanta. They'll be leaving on 11th June and returning a week later on 18th June. Tony and his family prefer flying business class.

To complete this scenario, we'll be:

Searching for flights
Selecting an offer from the search results
Creating a booking using the selected offer

Searching for flights

In our API, you create an offer request in order to search for flights.

tip

There's a new way to implement search, called multi-step search. You can find the guide here. Using the multi-step search flow will provide an enhanced search experience for the customer.

To build the payload you'll need the flight itinerary - which should include the origin(s), destination(s) and departure date(s) - and information about the passengers. Here's how we search for Tony's flights:

JavaScript
duffel.offerRequests.create({
  slices : [
    {
      origin: "NYC",
      destination: "ATL",
      departure_date: "2021-06-21"
    },
    {
      origin: "ATL",
      destination: "NYC",
      departure_date: "2021-07-21"
    }
  ],
  passengers: [{ type: "adult" }, { type: "adult" }, { age: 1 }],
  cabin_class: "business",
  return_offers: false
})

What is a slice?

A slice represents a journey that the passengers want to make between a particular origin and a particular destination on a particular date. For the origin and destination, simply provide the IATA code for an airport (for example ATL for Atlanta's Hartsfield-Jackson International Airport) or for a city (for example NYC for New York City, which covers multiple airports).

In our example, we have two slices: the outbound from New York to Atlanta, and the inbound from Atlanta to New York.

How do passengers work in the API?

When searching, you must provide the age of passengers aged under 18. For adults, you can just describe them using a type: adult.

This is important as airlines will charge different fares to passengers depending on their age.

When we create our booking later, we'll need to provide more information about the passengers like their names and dates of birth.

What will I get back?

We'll return an Offer Request object, echoing back your slices and passengers.

We'll use the id of the offer request itself to go and fetch the search results.

Each passenger is given an id, which we'll need to use to refer to that passenger when making a booking later.

Learn more

To see all of the options you can provide when creating an offer request and everything that we'll return back, check out our API reference.

Fetching the search results

To get the offers returned by our search - that is, the search results - we can use the "List offers" endpoint with the id of our offer request:

JavaScript
duffel.offers.list({
  offer_request_id: OFFER_REQUEST_ID
,
  sort: 'total_amount'
})

With the request above, you'll get the 50 cheapest offers. You can use sort parameter to decide what results come back first, and the limit parameters to pick how many results come back (with a maximum of 200).

If you want to work with more than 200 results, you'll need to paginate through batches returned by the API. This can be done manually with the before and after parameters - or automatically in our Ruby and Node.js client libraries:

JavaScript
const allOffers = duffel.offers.
  listWithGenerator({ offer_request_id: OFFER_REQUEST_ID
 }) 

for await (const offer of allOffers) {
  console.log("Offer " + offer.id + " costs " +
               offer.total_amount + " " + offer.total_currency)
}

Each offer is unique based on its itinerary and price. You'd show these offers to Tony in your user interface so he can pick the option that is best for him.

Learn more

To discover all of the filters and sort options available when listing offers and the data we'll return back, check out the "Offers" section in our API reference.

Selecting an offer from the search results

Offers get stale fairly quickly, and when they do, you are no longer able to book them.

Once Tony has picked an offer that works for him, you should retrieve the offer to get the most up to date version. You should do this when Tony picks an offer before you ask for his full passenger details and payment information.

To get the latest version of the offer, you can use the offer's id with the "Get a single offer" endpoint:

JavaScript
duffel.offers.get(OFFER_ID
)

You'll need to replace $OFFER_ID with the ID of one of the offers returned.

The total cost for an offer will be up-to-date once you retrieve it using this endpoint. Its price will be under the total_currency and total_amount attributes.

Slices and segments

The itinerary for a particular offer is described by its slices. Each offer will have the same slices as you specified when you created your Offer Request, but each slice will also contain one or more segments, describing in detail the flight(s) the passenger(s) will fly on.

For Tony's trip, let's say we are choosing an offer that departs from John F Kennedy Airport in New York (JFK) and has a stop in Washington Dulles Airport (IAD) on the way to ATL, and then no stops on the way back to JFK. On the outbound slice, you'll have 2 segments: one with JFK as its origin and IAD as its destination, and a second one from IAD to ATL. As the second slice is a direct flight with no stops, there's just a single segment from ATL back to JFK.

Inside those segments, you'll also find other important information like the airline and flight number, and the baggage included with that offer on each flight.

Learn more

If you'd like to get a complete look at the offer schema and the operations to retrieve a single offer or a paginated list of them, check out our API reference.

Creating a booking using the selected offer

We are finally ready to make the booking for Tony and his family. In the Duffel API, this is called creating an order. You'll only need 3 things at this point:

The ID of the offer you'd like to book
Basic necessary information about the passengers
Payment method and information to confirm the order

You'll collect #2 and #3 in your checkout flow. During that flow and after you confirm the booking, there are some important legal notices that you must display to make sure that the customer understands how their data will be used and the rules that apply to their booking.

You should charge the customer yourself before creating the order.

To create an order, use the "Create an order" endpoint:

JavaScript
duffel.orders.create({
  selected_offers: [OFFER_ID
],
  payments: [
    {
      type: "balance",
      currency: TOTAL_CURRENCY
,
      amount: TOTAL_AMOUNT
    }
  ],
  passengers: [
    {
      phone_number: "+442080160508",
      email: "tony@example.com",
      born_on: "1980-07-24",
      title: "mr",
      gender: "m",
      family_name: "Stark",
      given_name: "Tony",
      infant_passenger_id: INFANT_PASSENGER_ID
,
      id: ADULT_PASSENGER_ID_1
    },
    {
      phone_number: "+442080160509",
      email: "potts@example.com",
      born_on: "1983-11-02",
      title: "mrs",
      gender: "m",
      family_name: "Potts",
      given_name: "Pepper",
      id: ADULT_PASSENGER_ID_2
    },
    {
      phone_number: "+442080160506",
      email: "morgan@example.com",
      born_on: "2019-08-24",
      title: "mrs",
      gender: "f",
      family_name: "Stark",
      given_name: "Morgan",
      id: INFANT_PASSENGER_ID
    }
  ]
})

Selected offers

This attribute is an array that must contain a single offer ID: Replace $OFFER_ID with the one for the offer you'd like to book.

Payments

This is an array of payment objects. Currently, we only support a single payment. There are two possible values for a payment's type:

arc_bsp_cash if you are a registered IATA travel agent and you are using your own airline relationships with Duffel.
balance if you are using Managed Content. Follow the "Collecting Customer Card Payments" guide if you want to collect the payment directly from your customer's card and use it here.

You'll also need to include the currency of the payment ($TOTAL_CURRENCY) in ISO 4217 format — it should match the offer's total_currency — and the total amount ($TOTAL_AMOUNT) of the order, which should match the offer's total_amount.

Passengers

When creating an order you also need to provide information about all of the passengers.

To do this, we'll refer to each passenger using their id from our Offer Request. To do this, simply replace the $ADULT_PASSENGER_ID_1, $ADULT_PASSENGER_ID_2 and $INFANT_PASSENGER_ID from the example above.

Additionally, you'll need to provide each passenger's name, date of birth, gender, email and phone number.

If there are any infant passengers (that is, passengers aged 0 or 1 on the date of the last flight), you must specify which of the adult passengers will be responsible for them. To do that, you'll need to assign the infant's passenger id to the responsible adult's infant_passenger_id. All infants must have unique responsible adults.

Learn more

If you'd like to get a complete look at data you can provide when creating an order and what you'll get back, check out our API reference.

Keep Learning

All set! Tony and his family have been booked on their flights. The order returned by the API includes the airline's booking_reference, which you'd use to find the booking on the airline's website. The order can be retrieved any time by its id.

Where to go from here?