Implementation Guides

Quick Start

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

You can follow along with curl in your terminal, script the flow using your preferred programming language or try the API in an HTTP client like Postman.

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 sandbox access token from the "Access tokens" page in your Dashboard

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:

Curl

1
curl -X POST --compressed "https://api.duffel.com/air/offer_requests" \
2
-H "Accept-Encoding: gzip" \
3
-H "Accept: application/json" \
4
-H "Content-Type: application/json" \
5
-H "Duffel-Version: beta" \
6
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
7
-d '{
8
"data": {
9
"slices" : [
10
{
11
"origin": "NYC",
12
"destination": "ATL",
13
"departure_date": "2021-06-21"
14
},
15
{
16
"origin": "ATL",
17
"destination": "NYC",
18
"departure_date": "2021-07-21"
19
}
20
],
21
"passengers": [{ "type": "adult" }, { "type": "adult" }, { "age": 1 }],
22
"cabin_class": "business"
23
}
24
}'
25

You'll need to replace <YOUR_ACCESS_TOKEN> with the access token you created earlier.

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.

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

The interesting bit is the offers, which are the results of our search.

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

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:

Curl

1
curl -X GET --compressed "https://api.duffel.com/air/offers/<ID>" \
2
-H "Accept-Encoding: gzip" \
3
-H "Accept: application/json" \
4
-H "Duffel-Version: beta" \
5
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
6

You'll need to replace <YOUR_ACCESS_TOKEN> with the access token you created earlier and <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 should charge the customer yourself before creating the order.

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

Curl

1
curl -X POST --compressed "https://api.duffel.com/air/orders" \
2
-H "Accept-Encoding: gzip" \
3
-H "Accept: application/json" \
4
-H "Content-Type: application/json" \
5
-H "Duffel-Version: beta" \
6
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
7
-d '{
8
"data": {
9
"selected_offers": [
10
"off_0001"
11
],
12
"payments": [
13
{
14
"type" : "balance",
15
"currency" : "GBP",
16
"amount" : "647.00"
17
}
18
],
19
"passengers": [
20
{

You'll need to replace <YOUR_ACCESS_TOKEN> with the access token you created earlier.

caution

If you receive a 500 Internal Server Error when trying to create an order in production, it may have still been created on the airline’s side. Please contact Duffel support before trying the request again.

Selected offers

This attribute is an array that must contain a single offer ID: 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 Duffel Content

You'll also need to include the currency of the payment in ISO 4217 format — it should match the offer's total_currency — and the 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.

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?