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).
Endpoint
GET https://api.duffel.com/air/offer_requests/{id}
Request
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
{"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","country_name": "United Kingdom","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": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","iata_city_code": "NYC","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"},"airports": [{"time_zone": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"}}]},"departure_date": "2020-04-24"}],"passengers": [{"type": "adult","loyalty_programme_accounts": [{"airline_iata_code": "BA","account_number": "12901014"}],"id": "pas_00009hj8USM7Ncg31cBCL","given_name": "Amelia","family_name": "Earhart","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","fare_basis_code": "OXZ0RO","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","logo_symbol_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/BA.svg","logo_lockup_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-lockup/BA.svg","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"marketing_carrier_flight_number": "1234","marketing_carrier": {"name": "British Airways","logo_symbol_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/BA.svg","logo_lockup_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-lockup/BA.svg","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"id": "seg_00009htYpSCXrwaB9Dn456","duration": "PT02H26M","distance": "424.2","destination_terminal": "5","destination": {"time_zone": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"}},"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","country_name": "United Kingdom","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": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","iata_city_code": "NYC","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"},"airports": [{"time_zone": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"}}]},"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","payment_required_by": "2020-01-17T10:42:14Z"},"passengers": [{"type": "adult","loyalty_programme_accounts": [{"airline_iata_code": "BA","account_number": "12901014"}],"id": "pas_00009hj8USM7Ncg31cBCL","given_name": "Amelia","family_name": "Earhart","age": 14}],"passenger_identity_documents_required": false,"owner": {"name": "British Airways","logo_symbol_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/BA.svg","logo_lockup_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-lockup/BA.svg","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": {"penalty_currency": "GBP","penalty_amount": "100.00","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"}}
List offer requests
Retrieves a paginated list of your offer requests. The results may be returned in any order.
Query parameters
A cursor pointing to the previous page of records. For more information on how to paginate through records, see the Pagination section.
Example:
"g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="A cursor pointing to the next page of records. For more information on how to paginate through records, see the Pagination section.
Example:
"g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB="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:
1Default value:
50Endpoint
GET https://api.duffel.com/air/offer_requests
Request
curl -X GET --compressed "https://api.duffel.com/air/offer_requests?after=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&before=g2wAAAACbQAAABBBZXJvbWlzdC1LaGFya2l2bQAAAB=&limit=1" \-H "Accept-Encoding: gzip" \-H "Accept: application/json" \-H "Duffel-Version: beta" \-H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"
Response
{"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","country_name": "United Kingdom","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": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","iata_city_code": "NYC","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"},"airports": [{"time_zone": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"}}]},"departure_date": "2020-04-24"}],"passengers": [{"type": "adult","loyalty_programme_accounts": [{"airline_iata_code": "BA","account_number": "12901014"}],"id": "pas_00009hj8USM7Ncg31cBCL","given_name": "Amelia","family_name": "Earhart","age": 14}],"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.
Query parameters
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:
falseDefault value:
trueThe maximum amount of time in milliseconds to wait for each airline to respond. This timeout only applies to the response time of the call to the airline and doesn't include additional overhead added by Duffel.
Value should be between 2 seconds and 60 seconds. Any values outside the range will be ignored and the default supplier_timeout will be used.
If a value is set, the response will only include offers from airlines that returned within the given time.
If a value is not set, the response will only include offers from airlines that returned within the default supplier_timeout value of 20 seconds.
We recommend setting supplier_timeout lower than the timeout on the request sent to Duffel API as that will allow us to respond with the offers we received before your request times out with an empty response.
Example:
10000Default value:
20000Body parameters
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. You may only specify an age or a type – not both.
The slices that make up this offer request. One-way journeys can be expressed using one slice, whereas return trips will need two.
Endpoint
POST https://api.duffel.com/air/offer_requests
Request
curl -X POST --compressed "https://api.duffel.com/air/offer_requests?return_offers=false&supplier_timeout=10000" \-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_time": {"to": "17:00","from": "09:45"},"departure_date": "2020-04-24","arrival_time": {"to": "17:00","from": "09:45"}}],"passengers": [{"family_name": "Earhart","given_name": "Amelia","loyalty_programme_accounts": [{"account_number": "12901014","airline_iata_code": "BA"}],"type": "adult"},{"age": 14}],"max_connections": 0,"cabin_class": "economy"}}'
Response
{"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","country_name": "United Kingdom","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": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","iata_city_code": "NYC","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"},"airports": [{"time_zone": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"}}]},"departure_date": "2020-04-24"}],"passengers": [{"type": "adult","loyalty_programme_accounts": [{"airline_iata_code": "BA","account_number": "12901014"}],"id": "pas_00009hj8USM7Ncg31cBCL","given_name": "Amelia","family_name": "Earhart","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","fare_basis_code": "OXZ0RO","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","logo_symbol_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/BA.svg","logo_lockup_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-lockup/BA.svg","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"marketing_carrier_flight_number": "1234","marketing_carrier": {"name": "British Airways","logo_symbol_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/BA.svg","logo_lockup_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-lockup/BA.svg","id": "aln_00001876aqC8c5umZmrRds","iata_code": "BA"},"id": "seg_00009htYpSCXrwaB9Dn456","duration": "PT02H26M","distance": "424.2","destination_terminal": "5","destination": {"time_zone": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"}},"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","country_name": "United Kingdom","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": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","iata_city_code": "NYC","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"},"airports": [{"time_zone": "America/New_York","name": "John F. Kennedy International Airport","longitude": -73.778519,"latitude": 40.640556,"id": "arp_jfk_us","icao_code": "KJFK","iata_country_code": "US","iata_code": "JFK","city_name": "New York","city": {"name": "New York","id": "cit_nyc_us","iata_country_code": "US","iata_code": "NYC"}}]},"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","payment_required_by": "2020-01-17T10:42:14Z"},"passengers": [{"type": "adult","loyalty_programme_accounts": [{"airline_iata_code": "BA","account_number": "12901014"}],"id": "pas_00009hj8USM7Ncg31cBCL","given_name": "Amelia","family_name": "Earhart","age": 14}],"passenger_identity_documents_required": false,"owner": {"name": "British Airways","logo_symbol_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/BA.svg","logo_lockup_url": "https://assets.duffel.com/img/airlines/for-light-background/full-color-lockup/BA.svg","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": {"penalty_currency": "GBP","penalty_amount": "100.00","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"}}