Quick Start
Sign up for a Duffel account (it takes about 1 minute!)
Create a test access token from the "Access tokens" page in your Dashboard
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
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.
Searching for flights
Selecting an offer from the search results
Creating a booking using the selected offer
Searching 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.
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?
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?
type
: adult
.What will I get back?
slices
and passengers
.id
of the offer request itself to go and fetch the search results.id
, which we'll need to use to refer to that passenger when making a booking later.Learn more
Fetching the search results
id
of our offer request:JavaScript
duffel.offers.list({offer_request_id:OFFER_REQUEST_ID,sort: 'total_amount'})
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).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)}
Learn more
Selecting an offer from the search results
id
with the "Get a single offer" endpoint:JavaScript
duffel.offers.get(OFFER_ID)
$OFFER_ID
with the ID of one of the offers returned.total_currency
and total_amount
attributes.Slices and segments
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
.Learn more
Creating a booking using the selected offer
The ID of the offer you'd like to book
Basic necessary information about the passengers
Payment method and information to confirm the order
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
$OFFER_ID
with the one for the offer you'd like to book.Payments
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.
$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
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.id
to the responsible adult's infant_passenger_id
. All infants must have unique responsible adults.Learn more
Keep Learning
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
.