Offer Requests
To search for flights, you'll need to create an offer request. An offer request describes the passengers and where and when they want to travel (in the form of a list of slices). It may also include additional filters (e.g. a particular cabin to travel in).
Schema
cabin_class
enum
The cabin that the passengers want to travel in
Possible values:
"first", "business", "premium_economy", or "economy"created_at
datetime
The ISO 8601 datetime at which the offer request was created
Example:
"2020-02-12T15:21:01.927Z"id
string
Duffel's unique identifier for the offer request
Example:
"orq_00009hjdomFOCJyxHG7k7k"live_mode
boolean
Whether the offer request was created in live mode. This field will be set to true if the offer request was created in live mode, or false if it was created in test mode.
Example:
falseoffers
list
The offers returned by the airlines
passengers
list
The passengers who want to travel. A passenger will have only a type or an age.
slices
list
The slices that make up this offer request. One-way journeys can be expressed using one slice, whereas return trips will need two.
List offer requests
Retrieves a paginated list of your offer requests. The results may be returned in any order.
Endpoint
GEThttps://api.duffel.com/air/offer_requests
Query Parameters
after
string
A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.
Example:
"g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="before
string
A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.
Example:
"g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="limit
integer
The maximum number of records to return per page. Defaults to 50.
May be set to any integer between 1 and 200. For more information on how to paginate through records, see the Pagination section.
Example:
1Request example
curl -X GET --compressed "https://api.duffel.com/air/offer_requests" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Duffel-Version: beta" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response example
{"meta": {"limit": 50,"after": "g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="},"data": [{"slices": [{"origin_type": "airport","origin": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"destination_type": "airport","destination": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"departure_date": "2020-04-24"}],"passengers": [{"type": "adult","id": "pas_00009hj8USM7Ncg31cBCL","age": 14}],"offers": [{"total_emissions_kg": "460","total_currency": "GBP","total_amount": "45.00","tax_currency": "GBP","tax_amount": "40.80","slices": [{"segments": [{"passengers": [{"passenger_id": "passenger_0","cabin_class_marketing_name": "Economy Basic","cabin_class": "economy","baggages": [{"type": "checked","quantity": 1}]}],"origin_terminal": "B","origin": {"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}},"operating_carrier_flight_number": "4321","operating_carrier": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"marketing_carrier_flight_number": "1234","marketing_carrier": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"id": "seg_00009htYpSCXrwaB9Dn456","duration": "PT02H26M","distance": "424.2","destination_terminal": "5","destination": {"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}},"departing_at": "2020-06-13T16:38:02","arriving_at": "2020-06-13T16:38:02","aircraft": {"name": "Airbus Industries A380","id": "arc_00009UhD4ongolulWd91Ky","iata_code": "380"}}],"origin_type": "airport","origin": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"id": "sli_00009htYpSCXrwaB9Dn123","fare_brand_name": "Basic","duration": "PT02H26M","destination_type": "airport","destination": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"conditions": {"change_before_departure": {"penalty_currency": "GBP","penalty_amount": "100.00","allowed": true}}}],"payment_requirements": {"requires_instant_payment": "false","price_guarantee_expires_at": "2020-01-17T10:42:14.545Z","payment_required_by": "2020-01-17T10:42:14.545Z"},"passengers": [{"type": "adult","id": "pas_00009hj8USM7Ncg31cBCL","age": 14}],"passenger_identity_documents_required": false,"owner": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"live_mode": true,"id": "off_00009htYpSCXrwaB9DnUm0","expires_at": "2020-01-17T10:42:14.545Z","created_at": "2020-01-17T10:12:14.545Z","conditions": {"refund_before_departure": {"penalty_currency": "GBP","penalty_amount": "100.00","allowed": true},"change_before_departure": {"allowed": true}},"base_currency": "GBP","base_amount": "30.20","allowed_passenger_identity_document_types": ["passport"]}],"live_mode": false,"id": "orq_00009hjdomFOCJyxHG7k7k","created_at": "2020-02-12T15:21:01.927Z","cabin_class": "economy"}]}
Create an offer request
To search for flights, you'll need to create an offer request. An offer request describes the passengers and where and when they want to travel (in the form of a list of slices). It may also include additional filters (e.g. a particular cabin to travel in).
We'll send your search to a range of airlines, and return your offer request back to you with a series of offers.
Each offer represents a set of flights you can buy from an airline at a particular price that meet your search criteria.
Inside the offers, you'll see your slices, but now each slice will also include a list of one or more specific flights (called segments) that the airline is offering to get the passengers where they want to go.
When presenting offers to your customers, you should always show the full name of the operating carrier of each segment
(slices[].segments[].operating_carrier.name). This must be displayed prominently on the first screen
where the offer is presented in order to comply with US regulations.
Endpoint
POSThttps://api.duffel.com/air/offer_requests
Query Parameters
return_offers
boolean
When set to true, the offer request resource returned will include all the offers returned by the airlines.
If set to false, the offer request resource won't include any offers. To retrieve the associated offers later, use the List Offers endpoint, specifying the offer_request_id. You should use this option if you want to take advantage of the pagination, sorting and filtering that the List Offers endpoint provides.
Example:
falseBody parameters
cabin_class
enum
The cabin that the passengers want to travel in
Possible values:
"first", "business", "premium_economy", or "economy"passengers
list
required
The passengers who want to travel. If you specify an age for a passenger, the type may differ for the same passenger in different offers due to airline's different rules. e.g. one airline may treat a 14 year old as an adult, and another as a young adult.
slices
list
required
The slices that make up this offer request. One-way journeys can be expressed using one slice, whereas return trips will need two.
Request example
curl -X POST --compressed "https://api.duffel.com/air/offer_requests" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Duffel-Version: beta" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \-d '{"data": {"slices": [{"origin": "LHR","destination": "JFK","departure_date": "2020-04-24"}],"passengers": [{"type": "adult"},{"age": 14}],"cabin_class": "economy"}}'
Response example
{"data": {"slices": [{"origin_type": "airport","origin": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"destination_type": "airport","destination": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"departure_date": "2020-04-24"}],"passengers": [{"type": "adult","id": "pas_00009hj8USM7Ncg31cBCL","age": 14}],"offers": [{"total_emissions_kg": "460","total_currency": "GBP","total_amount": "45.00","tax_currency": "GBP","tax_amount": "40.80","slices": [{"segments": [{"passengers": [{"passenger_id": "passenger_0","cabin_class_marketing_name": "Economy Basic","cabin_class": "economy","baggages": [{"type": "checked","quantity": 1}]}],"origin_terminal": "B","origin": {"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}},"operating_carrier_flight_number": "4321","operating_carrier": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"marketing_carrier_flight_number": "1234","marketing_carrier": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"id": "seg_00009htYpSCXrwaB9Dn456","duration": "PT02H26M","distance": "424.2","destination_terminal": "5","destination": {"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}},"departing_at": "2020-06-13T16:38:02","arriving_at": "2020-06-13T16:38:02","aircraft": {"name": "Airbus Industries A380","id": "arc_00009UhD4ongolulWd91Ky","iata_code": "380"}}],"origin_type": "airport","origin": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"id": "sli_00009htYpSCXrwaB9Dn123","fare_brand_name": "Basic","duration": "PT02H26M","destination_type": "airport","destination": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"conditions": {"change_before_departure": {"penalty_currency": "GBP","penalty_amount": "100.00","allowed": true}}}],"payment_requirements": {"requires_instant_payment": "false","price_guarantee_expires_at": "2020-01-17T10:42:14.545Z","payment_required_by": "2020-01-17T10:42:14.545Z"},"passengers": [{"type": "adult","id": "pas_00009hj8USM7Ncg31cBCL","age": 14}],"passenger_identity_documents_required": false,"owner": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"live_mode": true,"id": "off_00009htYpSCXrwaB9DnUm0","expires_at": "2020-01-17T10:42:14.545Z","created_at": "2020-01-17T10:12:14.545Z","conditions": {"refund_before_departure": {"penalty_currency": "GBP","penalty_amount": "100.00","allowed": true},"change_before_departure": {"allowed": true}},"base_currency": "GBP","base_amount": "30.20","allowed_passenger_identity_document_types": ["passport"]}],"live_mode": false,"id": "orq_00009hjdomFOCJyxHG7k7k","created_at": "2020-02-12T15:21:01.927Z","cabin_class": "economy"}}
Get a single offer request
Retrieves an offer request by its ID
Endpoint
GEThttps://api.duffel.com/air/offer_requests/{id}
URL parameters
id
string
required
Duffel's unique identifier for the offer request
Example:
"orq_00009hjdomFOCJyxHG7k7k"Request example
curl -X GET --compressed "https://api.duffel.com/air/offer_requests/{id}" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Duffel-Version: beta" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response example
{"data": {"slices": [{"origin_type": "airport","origin": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"destination_type": "airport","destination": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"departure_date": "2020-04-24"}],"passengers": [{"type": "adult","id": "pas_00009hj8USM7Ncg31cBCL","age": 14}],"offers": [{"total_emissions_kg": "460","total_currency": "GBP","total_amount": "45.00","tax_currency": "GBP","tax_amount": "40.80","slices": [{"segments": [{"passengers": [{"passenger_id": "passenger_0","cabin_class_marketing_name": "Economy Basic","cabin_class": "economy","baggages": [{"type": "checked","quantity": 1}]}],"origin_terminal": "B","origin": {"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}},"operating_carrier_flight_number": "4321","operating_carrier": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"marketing_carrier_flight_number": "1234","marketing_carrier": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"id": "seg_00009htYpSCXrwaB9Dn456","duration": "PT02H26M","distance": "424.2","destination_terminal": "5","destination": {"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}},"departing_at": "2020-06-13T16:38:02","arriving_at": "2020-06-13T16:38:02","aircraft": {"name": "Airbus Industries A380","id": "arc_00009UhD4ongolulWd91Ky","iata_code": "380"}}],"origin_type": "airport","origin": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"id": "sli_00009htYpSCXrwaB9Dn123","fare_brand_name": "Basic","duration": "PT02H26M","destination_type": "airport","destination": {"type": "airport","time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","iata_city_code": "LON","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"},"airports": [{"time_zone": "Europe/London","name": "Heathrow","longitude": -141.951519,"latitude": 64.068865,"id": "arp_lhr_gb","icao_code": "EGLL","iata_country_code": "GB","iata_code": "LHR","city_name": "London","city": {"name": "London","id": "cit_lon_gb","iata_country_code": "GB","iata_code": "LON"}}]},"conditions": {"change_before_departure": {"penalty_currency": "GBP","penalty_amount": "100.00","allowed": true}}}],"payment_requirements": {"requires_instant_payment": "false","price_guarantee_expires_at": "2020-01-17T10:42:14.545Z","payment_required_by": "2020-01-17T10:42:14.545Z"},"passengers": [{"type": "adult","id": "pas_00009hj8USM7Ncg31cBCL","age": 14}],"passenger_identity_documents_required": false,"owner": {"name": "British Airways","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"live_mode": true,"id": "off_00009htYpSCXrwaB9DnUm0","expires_at": "2020-01-17T10:42:14.545Z","created_at": "2020-01-17T10:12:14.545Z","conditions": {"refund_before_departure": {"penalty_currency": "GBP","penalty_amount": "100.00","allowed": true},"change_before_departure": {"allowed": true}},"base_currency": "GBP","base_amount": "30.20","allowed_passenger_identity_document_types": ["passport"]}],"live_mode": false,"id": "orq_00009hjdomFOCJyxHG7k7k","created_at": "2020-02-12T15:21:01.927Z","cabin_class": "economy"}}