Overview

Here are the building blocks to set up your first request.

Authentication

You'll need to include an access token in every request you make to the API.

To create an access token, head to your dashboard. When you create an access token, you'll be able to choose whether to give it read-only or read-write access.

Send your access token in the Authorization request header using the "Bearer" authentication scheme:

Shell
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Versioning

You'll need to send a Duffel-Version header with each request so we know which version of the API you want to use. For example:


Duffel-Version: v2

Please refer to the Versioning page to learn more about how we version our API.

MIME types

All responses from the API are in JSON format with UTF-8 encoding. An Accept header is required with every request:

Shell
Accept: application/json

All request bodies sent to the API should be in JSON format. A Content-Type header is required whenever you're sending a request body (i.e. for POST and PUT requests):

Shell
Content-Type: application/json

Compression

We recommend enabling compression for responses returned by the API, since they can be very large. To enable compression, send an Accept-Encoding header:

Accept-Encoding: gzip

You'll need to configure your HTTP client to decompress responses. Most clients will have this functionality built-in.

Request ID

All responses will contain an x-request-id header. The value in this header uniquely identifies the request/response.

Shell
x-request-id: Fs1ffv5QZAgVh6kATEST

We recommend you keep track of this header for debugging purposes. When interacting with the Duffel API support team providing this header will allow the team to give you prompt and personalised support.

Client Correlation ID

Sometimes, you may want to send your own ID in the headers so that you can correlate requests and responses sent from Duffel.

We also provide a header named x-client-correlation-id for that purpose.

All responses will contain an x-client-correlation-id header. The value in this header allows you to set your own client identifier per request/response.

Shell
x-client-correlation-id: Fs1ffv5QZAgVh6kATEST

When your API client does not set this header, it will have the same value as x-request-id in the response.

Device details

When you create a booking, you can optionally tell us about the device the end traveller used to make it. We use these details as signals for fraud detection, helping to protect you from fraudulent bookings and chargebacks.

Since requests to the Duffel API are usually made by your servers rather than by the traveller's device directly, you'll need to forward these details explicitly using two optional request headers:

x-duffel-device-ip is the IP address of the traveller's device. It must be a valid IPv4 or IPv6 address.
x-duffel-device-user-agent is the user agent of the traveller's device.

These headers are supported on our booking and payment endpoints:

For example, when creating an order:

Shell
curl -X POST --compressed "https://api.duffel.com/air/orders" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Duffel-Version: v2" \
  -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \
  -H "x-duffel-device-ip: 93.184.216.34" \
  -H "x-duffel-device-user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:150.0) Gecko/20100101 Firefox/150.0" \
  -d '{ ... }'

Both headers are optional and invalid values are discarded, so sending them will never cause a request to fail. We recommend including them whenever they're available to you.