API Reference

Test mode

You'll want to start building your integration in test mode.

Test mode is a "sandbox" which lets you use the Duffel API risk-free, with no danger of spending any money or booking flights you don't want!

You'll need to create a testing access token to use test mode. Head to your dashboard, make sure that you're in "Developer test mode" and create a token. Testing tokens are easy to recognize: they start with test_.

With a testing access token, you'll only be able to access resources created in test mode. With a live access token, you'll only be able to access resources created in live mode.

While using the Duffel API in test mode, you'll likely be interacting with airlines' sandbox environments. These environments are external to our systems so, unfortunately, we are not able to provide strong guarantees about their behaviour.

For example, an airline's sandbox might be out of action due to maintenance, or flight availability might be "used up" due to other users' bookings.

We want to make sure that you have a great integration experience, from your first requests all the way to production, and Duffel having no control over the airline sandboxes should not affect that. To help with this we have created our own sandbox "airline": Duffel Airways. Making this airline available in test mode means that the Duffel team can provide stronger guarantees around the behaviour as well as the reliability of this particular airline's sandbox, meaning that you can reliably search and book no matter what.

For now, you can only search and book with Duffel Airways. You can't cancel any orders you create or make other changes. Over time, we'll be expanding Duffel Airways to support all of the features offered in the API (for example cancellations).

We think that this functionality really helps when you're starting out your integration because it allows you to focus on building the foundations of your integration, but this comes with trade-offs. Duffel Airways presents limitations such as:

  • Reduced fidelity: The data returned by Duffel Airways is not backed by realistic flight schedules or prices
  • Limited interactions: Interacting with Duffel Airways requires specific content to be triggered. For more details, see 'Searching' guide below.


To get started with Duffel Airways, you'll need to search for flights by creating an Offer Request. You can use the following request, replacing <YOUR_ACCESS_TOKEN> with your own access token:

curl --compressed "https://api.duffel.com/air/offer_requests" \
-H "Content-Type: application/json" \
-H "Accept-Encoding: gzip" \
-H "Duffel-Version: beta" \
-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
-d '{
"data": {
"cabin_class": "economy",
"slices": [
"departure_date": "2021-02-09",
"destination": "JFK",
"origin": "LHR"
"passengers": [
"type": "adult"

Duffel Airways will only return offers for this exact offer request. Note that:

  1. cabin_class must be "economy"
  2. destination must be "JFK"
  3. origin must be "LHR"
  4. passengers must be [{"type": "adult"}]

For more information on creating offer requests, see 'Create an offer request'.

With the results from a search you will then be able to create orders, see 'Create an order'.

If you have any feedback on the Duffel Airways sandbox, drop us a line.