Batch Offer Requests

Batch offer requests are a mechanism for retrieving offers as they become available, instead of waiting for the entire offer payload to finish processing. They function as long-polling resources that you can repeatedly retrieve after creating them, returning whatever offers are available at the time or waiting for more to become available. Batches are expected to be consumed promptly, and as such, batch offer requests expire after one minute. However, offers remain accessible and can be retrieved using the offer request ID as usual.

Schema

client_key
string

A client key to allow the Duffel Ancillaries component to talk to the Duffel API to retrieve information about an offer and its ancillaries. Learn more about how to use this on https://duffel.com/docs/guides/ancillaries-component.

Example: "SFMyNTY.g2gDdAAAAANkAAlsaXZlX21vZGVkAAVmYWxzZWQAD29yZ2FuaXNhdGlvbl9pZG0AAAAab3JnXzAwMDA5VWhGY29ERGk5TTFTRjhiS2FkAAtyZXNvdXJjZV9pZG0AAAAab3JxXzAwMDBBVkZWZnFJUXFBWXpYeVRRVlVuBgDpOCvdhwFiAAFRgA.df1RmLeBFUR7r1WFHHiEksilfSZNLhmPX0nj5VOKWJ4"
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 resource

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: false
remaining_batches
number

The remaining number of batches of offers.

Example: 2
total_batches
number

The total number of batches of offers.

Example: 2

Create a batch offer request

A long-polling style API where you can kick off a search and then separately retrieve offers as they become available. The endpoint returns immediately with an ID and the number of batches to expect.

To retrieve the offers, please refer to the Show Batch Offer Request endpoint.

Query parameters

supplier_timeout
integer

The maximum amount of time in milliseconds to wait for each airline search to complete. This timeout applies to the response time of the call to the airline and includes some 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 airline searches that completed within the given time. If a value is not set, the response will only include offers from airline searches that completed within the default supplier_timeout value of 20 seconds. We recommend setting supplier_timeout lower than the timeout on the HTTP request you send 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: 10000
Default value: 20000

Body parameters

cabin_class
enum

The cabin that the passengers want to travel in

Possible values: "first", "business", "premium_economy", or "economy"
max_connections
integer

The maximum number of connections within any slice of the offer. For example 0 means a direct flight which will have a single segment within each slice and 1 means a maximum of two segments within each slice of the offer.

Example: 0
Default value: 1
passengers
listrequired

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.

private_fares

The private fare codes for this offer request. You can pass in multiple airlines with their specific private fare codes. The key is the airline's IATA code that provided the private fare code. The corporate_code and tour_code are provided to you by the airline and the tracking_reference is to identify your business by the airlines.

Example: {"QF":[{"corporate_code":"FLX53","tracking_reference":"ABN:2345678"}],"UA":[{"corporate_code":"1234","tour_code":"578DFL"}]}
slices
listrequired

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/batch_offer_requests

Request

curl -X POST --compressed "https://api.duffel.com/air/batch_offer_requests?supplier_timeout=10000" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Duffel-Version: v2" \
  -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"
        }
      }
    ],
    "private_fares": {
      "QF": [
        {
          "corporate_code": "FLX53",
          "tracking_reference": "ABN:2345678"
        }
      ],
      "UA": [
        {
          "corporate_code": "1234",
          "tour_code": "578DFL"
        }
      ]
    },
    "passengers": [
      {
        "family_name": "Earhart",
        "given_name": "Amelia",
        "loyalty_programme_accounts": [
          {
            "account_number": "12901014",
            "airline_iata_code": "BA"
          }
        ],
        "type": "adult"
      },
      {
        "age": 14
      },
      {
        "fare_type": "student"
      },
      {
        "age": 5,
        "fare_type": "contract_bulk_child"
      }
    ],
    "max_connections": 0,
    "cabin_class": "economy"
  }
}'

Response

{
  "data": {
    "total_batches": 2,
    "remaining_batches": 2,
    "live_mode": false,
    "id": "orq_00009hjdomFOCJyxHG7k7k",
    "created_at": "2020-02-12T15:21:01.927Z",
    "client_key": "SFMyNTY.g2gDdAAAAANkAAlsaXZlX21vZGVkAAVmYWxzZWQAD29yZ2FuaXNhdGlvbl9pZG0AAAAab3JnXzAwMDA5VWhGY29ERGk5TTFTRjhiS2FkAAtyZXNvdXJjZV9pZG0AAAAab3JxXzAwMDBBVkZWZnFJUXFBWXpYeVRRVlVuBgDpOCvdhwFiAAFRgA.df1RmLeBFUR7r1WFHHiEksilfSZNLhmPX0nj5VOKWJ4"
  }
}

Get a single batch offer request

A long-polling style API where you can kick off a search via "Create a batch offer request" and then separately retrieve offers as they become available (with this endpoint?).

Call this endpoint repeatedly to retrieve all the offers as they become available. The total_batches and remaining_batches properties can be used to estimate the remaining amount of work, although you may receive multiple batches at the same time if multiple batches are available. Once you get a response with remaining_batches of 0 you can stop requesting the endpoint as there are no more offers coming.

URL parameters

id
stringrequired

Duffel's unique identifier for the batch offer request

Example: "orq_00009hjdomFOCJyxHG7k7k"

Endpoint

GET https://api.duffel.com/air/batch_offer_requests/{id}

Request

curl -X GET --compressed "https://api.duffel.com/air/batch_offer_requests/{id}" \
  -H "Accept-Encoding: gzip" \
  -H "Accept: application/json" \
  -H "Duffel-Version: v2" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Response

{
  "data": {
    "total_batches": 2,
    "remaining_batches": 2,
    "offers": [
      {
        "total_emissions_kg": "460",
        "total_currency": "GBP",
        "total_amount": "45.00",
        "tax_currency": "GBP",
        "tax_amount": "40.80",
        "supported_passenger_identity_document_types": [
          "passport"
        ],
        "slices": [
          {
            "segments": [
              {
                "stops": [
                  {
                    "id": "sto_00009htYpSCXrwaB9Dn456",
                    "duration": "PT02H26M",
                    "departing_at": "2020-06-13T16:38:02",
                    "arriving_at": "2020-06-13T16:38:02",
                    "airport": {
                      "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",
                          "iata_city_code": "LON",
                          "city_name": "London",
                          "city": {
                            "name": "London",
                            "id": "cit_lon_gb",
                            "iata_country_code": "GB",
                            "iata_code": "LON"
                          }
                        }
                      ]
                    }
                  }
                ],
                "passengers": [
                  {
                    "passenger_id": "passenger_0",
                    "fare_basis_code": "OXZ0RO",
                    "cabin_class_marketing_name": "Economy Basic",
                    "cabin_class": "economy",
                    "cabin": {
                      "name": "economy",
                      "marketing_name": "Economy Basic",
                      "amenities": {
                        "wifi": {
                          "cost": "free",
                          "available": "true"
                        },
                        "seat": {
                          "type": "standard",
                          "pitch": "32",
                          "legroom": "standard"
                        },
                        "power": {
                          "available": "true"
                        }
                      }
                    },
                    "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",
                  "iata_city_code": "LON",
                  "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": "arl_00001876aqC8c5umZmrRds",
                  "iata_code": "BA",
                  "conditions_of_carriage_url": "https://www.britishairways.com/en-gb/information/legal/british-airways/general-conditions-of-carriage"
                },
                "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": "arl_00001876aqC8c5umZmrRds",
                  "iata_code": "BA",
                  "conditions_of_carriage_url": "https://www.britishairways.com/en-gb/information/legal/british-airways/general-conditions-of-carriage"
                },
                "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",
                  "iata_city_code": "NYC",
                  "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",
              "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",
                  "iata_city_code": "LON",
                  "city_name": "London",
                  "city": {
                    "name": "London",
                    "id": "cit_lon_gb",
                    "iata_country_code": "GB",
                    "iata_code": "LON"
                  }
                }
              ]
            },
            "ngs_shelf": 1,
            "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",
                  "iata_city_code": "LON",
                  "city_name": "London",
                  "city": {
                    "name": "London",
                    "id": "cit_lon_gb",
                    "iata_country_code": "GB",
                    "iata_code": "LON"
                  }
                }
              ]
            },
            "conditions": {
              "priority_check_in": "true",
              "priority_boarding": "true",
              "change_before_departure": {
                "penalty_currency": "GBP",
                "penalty_amount": "100.00",
                "allowed": true
              },
              "advance_seat_selection": "true"
            },
            "comparison_key": "BmlZDw=="
          }
        ],
        "private_fares": [
          {
            "type": "corporate",
            "tracking_reference": "ABN:2345678",
            "tour_code": "578DFL",
            "corporate_code": "FLX53"
          }
        ],
        "payment_requirements": {
          "requires_instant_payment": false,
          "price_guarantee_expires_at": "2020-01-17T10:42:14Z",
          "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",
            "fare_type": "contract_bulk",
            "family_name": "Earhart",
            "age": 14
          }
        ],
        "passenger_identity_documents_required": false,
        "partial": true,
        "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": "arl_00001876aqC8c5umZmrRds",
          "iata_code": "BA",
          "conditions_of_carriage_url": "https://www.britishairways.com/en-gb/information/legal/british-airways/general-conditions-of-carriage"
        },
        "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"
      }
    ],
    "live_mode": false,
    "id": "orq_00009hjdomFOCJyxHG7k7k",
    "created_at": "2020-02-12T15:21:01.927Z",
    "client_key": "SFMyNTY.g2gDdAAAAANkAAlsaXZlX21vZGVkAAVmYWxzZWQAD29yZ2FuaXNhdGlvbl9pZG0AAAAab3JnXzAwMDA5VWhGY29ERGk5TTFTRjhiS2FkAAtyZXNvdXJjZV9pZG0AAAAab3JxXzAwMDBBVkZWZnFJUXFBWXpYeVRRVlVuBgDpOCvdhwFiAAFRgA.df1RmLeBFUR7r1WFHHiEksilfSZNLhmPX0nj5VOKWJ4"
  }
}