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 a JavaScript client library in JavaScript, 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.

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:

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",
})

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).

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.

What will I get back?

An id for the offer request. You may use this ID to retrieve the offer request later. The response will include an array of offers.

Selecting an offer from the search results

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:

duffel.offers.get(OFFER_ID)

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.

Creating a booking using the selected offer

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. To create an order, use the "Create an order" endpoint:

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
    }
  ]
})

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.