A service for consumers to book an air shipment, optionally applying product prices supplied via the Airfreight Quote API. Carries IATA three-letter airport codes, air waybill and HAWB service types, HS codes and IATA dangerous-goods flags.
{
"openapi" : "3.0.1",
"info" : {
"title" : "BookingAir",
"description" : "The Kuehne+Nagel Air Booking API is used to communicate with B2B platforms. It supports the airfreight booking process. The API is used to request and receive bookings (optionally using price references).",
"termsOfService" : "https://onlineservices.kuehne-nagel.com/fa/site/static/KN_FreightNet_terms_and_conditions_en.pdf",
"contact" : {
"name" : "Book API Support",
"url" : "https://home.kuehne-nagel.com/en/service-request-api-air?lead_topic=api-support-air"
},
"version" : "v2",
"x-api-version" : "2.1.0",
"x-api-id" : "6990dff6-e802-4d92-a5e3-3bb15e8ec6db",
"x-api-guideline-version" : "1.11.6"
},
"servers" : [ {
"url" : "https://gateway.api.kuehne-nagel.com/booking/air/v2"
} ],
"security" : [ {
"default" : [ ]
} ],
"paths" : {
"/bookings" : {
"put" : {
"tags" : [ "booking" ],
"summary" : "Update an air booking",
"description" : "Update air booking",
"parameters" : [ {
"$ref" : "#/components/parameters/trackingNumberParam"
}, {
"$ref" : "#/components/parameters/uniqueReferenceParam"
} ],
"requestBody" : {
"description" : "The request containing booking details for a new booking to be created",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Booking"
},
"examples" : {
"requestExample1" : {
"$ref" : "#/components/examples/BookingRequestExampleDD"
},
"requestExample2" : {
"$ref" : "#/components/examples/BookingRequestExampleAA"
},
"requestExample3" : {
"$ref" : "#/components/examples/BookingRequestExampleAAWithPriceReference"
}
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "OK",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/BookingResponse"
}
}
}
},
"default" : {
"description" : "Default error sample response",
"content" : {
"application/problem+json" : {
"schema" : {
"$ref" : "#/components/schemas/ErrorResponse"
},
"examples" : {
"errorExample1" : {
"$ref" : "#/components/examples/Error400Example1"
},
"errorExample2" : {
"$ref" : "#/components/examples/Error400Example2"
},
"errorExample3" : {
"$ref" : "#/components/examples/Error401Example"
},
"errorExample4" : {
"$ref" : "#/components/examples/Error500Example"
},
"errorExample5" : {
"$ref" : "#/components/examples/Error503Example"
}
}
}
}
}
},
"security" : [ {
"default" : [ ]
} ],
"x-codegen-request-body-name" : "body",
"x-auth-type" : "Application & Application User",
"x-throttling-tier" : "10KPerMin"
},
"post" : {
"tags" : [ "booking" ],
"summary" : "Create air booking",
"description" : "Create air booking",
"requestBody" : {
"description" : "The request containing booking details for a new booking to be created",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Booking"
},
"examples" : {
"requestExample1" : {
"$ref" : "#/components/examples/BookingRequestExampleDD"
},
"requestExample2" : {
"$ref" : "#/components/examples/BookingRequestExampleAA"
},
"requestExample3" : {
"$ref" : "#/components/examples/BookingRequestExampleAAWithPriceReference"
}
}
}
},
"required" : true
},
"responses" : {
"201" : {
"description" : "Created",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/BookingResponse"
}
}
}
},
"default" : {
"description" : "Default error sample response",
"content" : {
"application/problem+json" : {
"schema" : {
"$ref" : "#/components/schemas/ErrorResponse"
},
"examples" : {
"errorExample1" : {
"$ref" : "#/components/examples/Error400Example1"
},
"errorExample2" : {
"$ref" : "#/components/examples/Error400Example2"
},
"errorExample3" : {
"$ref" : "#/components/examples/Error401Example"
},
"errorExample4" : {
"$ref" : "#/components/examples/Error500Example"
},
"errorExample5" : {
"$ref" : "#/components/examples/Error503Example"
}
}
}
}
}
},
"security" : [ {
"default" : [ ]
} ],
"x-codegen-request-body-name" : "body",
"x-auth-type" : "Application & Application User",
"x-throttling-tier" : "10KPerMin"
},
"delete" : {
"tags" : [ "booking" ],
"summary" : "Delete air booking",
"description" : "Delete air booking",
"parameters" : [ {
"$ref" : "#/components/parameters/trackingNumberParam"
}, {
"$ref" : "#/components/parameters/uniqueReferenceParam"
} ],
"responses" : {
"204" : {
"description" : "No Content"
},
"default" : {
"description" : "Default error sample response",
"content" : {
"application/problem+json" : {
"schema" : {
"$ref" : "#/components/schemas/ErrorResponse"
},
"examples" : {
"errorExample1" : {
"$ref" : "#/components/examples/Error401Example"
},
"errorExample2" : {
"$ref" : "#/components/examples/Error404Example"
},
"errorExample3" : {
"$ref" : "#/components/examples/Error500Example"
},
"errorExample4" : {
"$ref" : "#/components/examples/Error503Example"
}
}
}
}
}
},
"security" : [ {
"default" : [ ]
} ],
"x-auth-type" : "Application & Application User",
"x-throttling-tier" : "10KPerMin"
}
}
},
"components" : {
"schemas" : {
"Booking" : {
"required" : [ "cargo", "customsClearanceByKn", "destination", "incoterm", "origin" ],
"type" : "object",
"properties" : {
"uniqueReference" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "The unique reference to identify the shipment",
"example" : "ABCD12345678"
},
"priceReference" : {
"type" : "string",
"description" : "Unique price reference number of a previously provided pricing",
"format" : "uuid",
"example" : "4396495d-3329-476b-8693-99869f715ba1"
},
"houseAirWaybillNumber" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "HAWB Number of the shipment",
"example" : "123-12345675"
},
"customerRequiredAirWaybillText" : {
"maxLength" : 500,
"minLength" : 1,
"type" : "string",
"description" : "Customer required AWB Text",
"example" : "This is a Customer required AWB Text example"
},
"origin" : {
"$ref" : "#/components/schemas/Origin"
},
"destination" : {
"$ref" : "#/components/schemas/Destination"
},
"cargo" : {
"$ref" : "#/components/schemas/Cargo"
},
"commercialInvoiceAmount" : {
"$ref" : "#/components/schemas/Amount"
},
"notifyAddress" : {
"$ref" : "#/components/schemas/Address"
},
"notifyContact" : {
"$ref" : "#/components/schemas/Contact"
},
"isLetterOfCredit" : {
"type" : "boolean",
"description" : "Denotes usage of letter of credit",
"example" : false,
"default" : false
},
"letterOfCreditLatestDepartureDate" : {
"type" : "string",
"description" : "Latest departure date of letter of credit",
"format" : "date-time",
"example" : "2024-05-02T07:55:53.356Z"
},
"letterOfCreditExpiryDate" : {
"type" : "string",
"description" : "Expiry date of letter of credit",
"format" : "date-time",
"example" : "2024-05-04T07:55:53.356Z"
},
"letterOfCreditNumber" : {
"maxLength" : 35,
"type" : "string",
"description" : "Letter of credit number",
"example" : "20200101ABCDE"
},
"incoterm" : {
"maxLength" : 3,
"type" : "string",
"description" : "Defines the commercial terms for the transaction. The validation depends on the routing.",
"example" : "EXW",
"x-extensible-enum" : [ "EXW", "FCA", "FOB", "CIF", "CFR", "CPT", "CIP", "DAT", "DDU", "DDP", "DAP" ]
},
"incotermPlace" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "IncoTerm place",
"example" : "Hamburg"
},
"freightPayerAddress" : {
"$ref" : "#/components/schemas/Address"
},
"exportQuotationNumber" : {
"maxLength" : 64,
"type" : "string",
"description" : "The number of the quotation that has been requested by KN Freight Net",
"example" : "123654789"
},
"customerSpecificAgreementName" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Customer Specific Agreement Name",
"example" : "PX-TA"
},
"customerReferences" : {
"minItems" : 0,
"type" : "array",
"description" : "Collection of customer references",
"items" : {
"$ref" : "#/components/schemas/Reference"
}
},
"insuranceAmount" : {
"$ref" : "#/components/schemas/Amount"
},
"customsClearanceByKn" : {
"type" : "boolean",
"description" : "Denotes if customs clearance should be arranged by KN",
"example" : false
},
"includesDefenceCommodity" : {
"type" : "boolean",
"description" : "Indicates if the shipment contains defence commodities",
"example" : false
},
"isImportBooking" : {
"type" : "boolean",
"description" : "Denotes if requested import booking.",
"example" : false
},
"knOfficeCode" : {
"maxLength" : 9,
"type" : "string",
"description" : "Logical address or Company.code+Branch.code",
"example" : "HKKNHKHKG"
},
"product" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "KN product",
"example" : "GEN-PX"
},
"serviceType" : {
"maxLength" : 8,
"type" : "string",
"description" : "Service type of the shipment",
"example" : "HAWB",
"x-extensible-enum" : [ "HAWB", "IATA", "COURIER", "SEAAIR", "AIRSEA", "MISC" ]
},
"tradeControlDetails" : {
"$ref" : "#/components/schemas/TradeControlDetails"
}
}
},
"Address" : {
"required" : [ "city", "countryCode", "name" ],
"type" : "object",
"properties" : {
"name" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Name of the customer",
"example" : "Dummy customer Inc."
},
"name2" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Name of the customer - 2nd part",
"example" : "Further name of Dummy customer Inc"
},
"street" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Street name",
"example" : "Dummy street name"
},
"street2" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Street name - 2nd part",
"example" : "Other part of street name"
},
"city" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "City name",
"example" : "London"
},
"countryCode" : {
"type" : "string",
"description" : "Country code",
"format" : "iso-3166",
"example" : "GB"
},
"stateCode" : {
"maxLength" : 3,
"minLength" : 1,
"type" : "string",
"description" : "State code",
"example" : "LXE"
},
"poBox" : {
"maxLength" : 10,
"minLength" : 1,
"type" : "string",
"description" : "PO Box",
"example" : "52011"
},
"postalCode" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Postal code",
"example" : "5201AX"
},
"customerReferences" : {
"minItems" : 0,
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Reference"
}
}
}
},
"Amount" : {
"required" : [ "amount", "currency" ],
"type" : "object",
"properties" : {
"amount" : {
"type" : "number",
"description" : "Value of the price",
"format" : "double",
"example" : 10.5
},
"currency" : {
"type" : "string",
"description" : "The ISO 4217 standard three-letter code of a currency.",
"format" : "iso-4217",
"example" : "EUR"
}
}
},
"Cargo" : {
"required" : [ "description", "isDangerousGoods", "weightInKilogram" ],
"type" : "object",
"properties" : {
"description" : {
"maxLength" : 256,
"type" : "string",
"description" : "Description of cargo",
"example" : "A lot of chairs"
},
"numberOfPieces" : {
"type" : "integer",
"description" : "Number of pieces",
"format" : "int32",
"example" : 42
},
"shippersLoadAndCount" : {
"type" : "integer",
"description" : "Shippers load and count",
"format" : "int32",
"example" : 42
},
"dimensions" : {
"minItems" : 1,
"type" : "array",
"description" : "Dimensions of transported goods",
"items" : {
"$ref" : "#/components/schemas/Dimensions"
}
},
"hsCodes" : {
"minItems" : 0,
"type" : "array",
"description" : "Collection of HSCodes",
"items" : {
"$ref" : "#/components/schemas/HSCode"
}
},
"generalHandlingText" : {
"maxLength" : 1000,
"minLength" : 1,
"type" : "string",
"description" : "General handling text",
"example" : "This is a general handling text example"
},
"weightInKilogram" : {
"type" : "number",
"description" : "Weight of cargo in kilograms",
"format" : "double",
"example" : 42.5
},
"volumeInCubicMeter" : {
"type" : "number",
"description" : "Volume of cargo in cubic meters",
"format" : "double",
"example" : 42.5
},
"isDangerousGoods" : {
"type" : "boolean",
"description" : "Identifies whether the booking is applicable for dangerous goods",
"example" : false
},
"dangerousGoodsPositions" : {
"minItems" : 0,
"type" : "array",
"description" : "Collection of Dangerous goods positions",
"items" : {
"$ref" : "#/components/schemas/DangerousGoodsPosition"
}
}
}
},
"Contact" : {
"required" : [ "lastName" ],
"type" : "object",
"properties" : {
"email" : {
"maxLength" : 256,
"minLength" : 1,
"type" : "string",
"description" : "E-mail address",
"format" : "email",
"example" : "donotreply@kuehne-nagel.com"
},
"firstName" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "First name",
"example" : "John"
},
"lastName" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Last name",
"example" : "Smith"
},
"phone" : {
"maxLength" : 256,
"minLength" : 1,
"type" : "string",
"description" : "Contact phone number",
"example" : "123456789"
}
}
},
"DangerousGoodsPosition" : {
"required" : [ "numberOfPackages", "packageType" ],
"type" : "object",
"properties" : {
"numberOfPackages" : {
"type" : "number",
"description" : "Number of packages",
"format" : "double",
"example" : 42
},
"packageType" : {
"maxLength" : 3,
"type" : "string",
"description" : "Package type",
"example" : "PCS"
},
"overpackNumber" : {
"maxLength" : 64,
"type" : "string",
"description" : "Overpack Number",
"example" : "#A01"
},
"limitedQuantityGrossWeightInKg" : {
"type" : "number",
"description" : "Limited Quatity Gross Weight in KG.",
"format" : "double",
"example" : 3.2
},
"dangerousGoodsDetails" : {
"minItems" : 0,
"type" : "array",
"description" : "List of dangerous goods details",
"items" : {
"$ref" : "#/components/schemas/DangerousGoodsDetail"
}
}
}
},
"DangerousGoodsDetail" : {
"required" : [ "properShippingName", "quantityUoM", "unNumber" ],
"type" : "object",
"properties" : {
"properShippingName" : {
"maxLength" : 512,
"type" : "string",
"description" : "Proper shipping name",
"example" : "SAFETY DEVICES"
},
"quantityUoM" : {
"maxLength" : 2,
"type" : "string",
"description" : "Unit of measurement of specified quantity",
"example" : "KG",
"x-extensible-enum" : [ "KG", "L" ]
},
"dgClass" : {
"maxLength" : 4,
"type" : "string",
"description" : "DG class",
"example" : "1.4D"
},
"extensionForMixtureOrSolution" : {
"maxLength" : 256,
"type" : "string",
"description" : "Extension for mixture or solution",
"example" : "PETROLEUM CRUDE OIL"
},
"importantDgText" : {
"maxLength" : 512,
"type" : "string",
"description" : "Important DG text",
"example" : "Wooden boxes"
},
"isEmpty" : {
"type" : "boolean",
"description" : "Denotes if is empty",
"example" : false,
"default" : false
},
"isExceptedQuantity" : {
"type" : "boolean",
"description" : "Denotes if is excepted quantity",
"example" : false,
"default" : false
},
"isHot" : {
"type" : "boolean",
"description" : "Denotes if the good is hot",
"example" : false,
"default" : false
},
"isLimitedQuantity" : {
"type" : "boolean",
"description" : "Denotes if the quantity is limited",
"example" : false,
"default" : false
},
"isSalvagePackaging" : {
"type" : "boolean",
"description" : "Denotes if salvage packaging",
"example" : false,
"default" : false
},
"isWaste" : {
"type" : "boolean",
"description" : "Denotes if the good is waste",
"example" : false,
"default" : false
},
"isLithiumBattery" : {
"type" : "boolean",
"description" : "Denotes if this is a lithium battery according to Section II of the IATA Regulation, for which special regulations exist.",
"example" : false,
"default" : false
},
"isId8000" : {
"type" : "boolean",
"description" : "Denotes if this is a consumer commodity.",
"example" : false,
"default" : false
},
"isDryIceWithoutDg" : {
"type" : "boolean",
"description" : "Indicates if this is dry ice, for which no dangerous goods details exist.",
"example" : false,
"default" : false
},
"netExplosiveQuantityInKg" : {
"type" : "number",
"description" : "Net explosive quantity in KG",
"format" : "double",
"example" : 42.5
},
"packingGroup" : {
"maxLength" : 1,
"type" : "string",
"description" : "Packing group",
"example" : "1",
"x-extensible-enum" : [ "1", "2", "3" ]
},
"packingInstruction" : {
"maxLength" : 10,
"type" : "string",
"description" : "Packing instruction",
"example" : "967"
},
"quantityPerPackage" : {
"type" : "number",
"description" : "Quantity per package",
"format" : "double",
"example" : 42
},
"subsidiaryRisks" : {
"maxItems" : 4,
"minItems" : 0,
"type" : "array",
"description" : "Subsidiary risks. Max 4 strings, max 4 chars long",
"example" : [ "1.4D" ],
"items" : {
"maxLength" : 4,
"type" : "string"
}
},
"unNumber" : {
"maxLength" : 4,
"type" : "string",
"description" : "Four-digit number assigned by the United Nations Committee of Experts on the Transport of Dangerous Goods to identify a substance or a particular group of substances",
"example" : "0001"
},
"radioactiveDetails" : {
"$ref" : "#/components/schemas/RadioactiveDetails"
}
}
},
"Destination" : {
"required" : [ "buyerAddress" ],
"type" : "object",
"properties" : {
"deliveryByKn" : {
"type" : "boolean",
"description" : "Denotes if delivery should be arranged by KN",
"example" : false
},
"buyerAddress" : {
"$ref" : "#/components/schemas/Address"
},
"airWaybillConsigneeAddress" : {
"$ref" : "#/components/schemas/Address"
},
"deliveryContact" : {
"$ref" : "#/components/schemas/Contact"
},
"deliveryAddress" : {
"$ref" : "#/components/schemas/Address"
},
"importAvailabilityTime" : {
"type" : "string",
"description" : "Import availability time",
"format" : "date-time",
"example" : "2024-05-03T07:55:53.356Z"
},
"deliveryHandlingText" : {
"maxLength" : 1000,
"minLength" : 1,
"type" : "string",
"description" : "Delivery handling text",
"example" : "Example delivery handling text"
},
"airportCode" : {
"pattern" : "^[A-Z]{3}$",
"type" : "string",
"description" : "The IATA airport code",
"example" : "JFK"
}
}
},
"Dimensions" : {
"required" : [ "heightInCentimeter", "lengthInCentimeter", "numberOfPieces", "widthInCentimeter" ],
"type" : "object",
"properties" : {
"numberOfPieces" : {
"type" : "integer",
"description" : "Number of pieces",
"format" : "int32",
"example" : 42
},
"heightInCentimeter" : {
"type" : "integer",
"description" : "Height in centimeter",
"format" : "int32",
"example" : 12
},
"lengthInCentimeter" : {
"type" : "integer",
"description" : "Length in centimeter",
"format" : "int32",
"example" : 12
},
"widthInCentimeter" : {
"type" : "integer",
"description" : "Width in centimeter",
"format" : "int32",
"example" : 12
}
}
},
"HSCode" : {
"required" : [ "code" ],
"type" : "object",
"properties" : {
"code" : {
"maxLength" : 18,
"minLength" : 1,
"type" : "string",
"description" : "Single HS code",
"example" : "870899"
},
"notes" : {
"maxLength" : 512,
"minLength" : 1,
"type" : "string",
"description" : "Detailed description of the HS Code",
"example" : "Civil aircraft parts"
}
}
},
"Origin" : {
"required" : [ "exportAvailabilityTime", "sellerAddress" ],
"type" : "object",
"properties" : {
"sellerAddress" : {
"$ref" : "#/components/schemas/Address"
},
"airWaybillShipperAddress" : {
"$ref" : "#/components/schemas/Address"
},
"pickupContact" : {
"$ref" : "#/components/schemas/Contact"
},
"pickupAddress" : {
"$ref" : "#/components/schemas/Address"
},
"pickupByKn" : {
"type" : "boolean",
"description" : "Denotes if pickup should be arranged by KN",
"example" : false
},
"pickupHandlingText" : {
"maxLength" : 1000,
"minLength" : 1,
"type" : "string",
"description" : "Pickup handling text",
"example" : "Example pickup handling text"
},
"exportAvailabilityTime" : {
"type" : "string",
"description" : "Export availability time",
"format" : "date-time",
"example" : "2024-05-02T07:55:53.356Z"
},
"airportCode" : {
"pattern" : "^[A-Z]{3}$",
"type" : "string",
"description" : "The IATA airport code",
"example" : "FRA"
}
}
},
"RadioactiveDetails" : {
"type" : "object",
"properties" : {
"packageCategory" : {
"maxLength" : 20,
"type" : "string",
"description" : "Radioactive package category",
"example" : "I-White"
},
"transportIndex" : {
"maxLength" : 20,
"type" : "string",
"description" : "Radioactive transport index",
"example" : "0"
},
"typeOfPackage" : {
"maxLength" : 20,
"type" : "string",
"description" : "Radioactive type of package",
"example" : "LIQ"
},
"contents" : {
"maxLength" : 35,
"type" : "string",
"description" : "Radioactive contents",
"example" : "Th-227"
},
"maximumActivity" : {
"maxLength" : 20,
"type" : "string",
"description" : "Radioactive maximum activity",
"example" : "3"
},
"unitOfMeasure" : {
"maxLength" : 20,
"type" : "string",
"description" : "Unit of measure",
"example" : "MBQ"
}
}
},
"Reference" : {
"required" : [ "code", "value" ],
"type" : "object",
"properties" : {
"code" : {
"maxLength" : 3,
"minLength" : 1,
"type" : "string",
"description" : "Reference code",
"example" : "INN"
},
"value" : {
"maxLength" : 35,
"minLength" : 1,
"type" : "string",
"description" : "Reference value",
"example" : "ABCD1234567890"
}
}
},
"TradeControlDetails" : {
"required" : [ "exportControl", "exportCustomsClearance", "importControl", "importCustomsClearance", "military", "sanctions", "transitControl" ],
"type" : "object",
"properties" : {
"sanctions" : {
"type" : "boolean",
"description" : "Indicates whether the shipment is subject to sanctions or embargoes",
"example" : true
},
"exportControl" : {
"type" : "boolean",
"description" : "Indicates whether the shipment is subject to export control",
"example" : true
},
"importControl" : {
"type" : "boolean",
"description" : "Indicates whether the shipment is subject to import control",
"example" : true
},
"transitControl" : {
"type" : "boolean",
"description" : "Indicates whether the shipment is subject to transit control",
"example" : true
},
"military" : {
"type" : "boolean",
"description" : "Indicates whether the shipment is related to defense or the military",
"example" : true
},
"exportCustomsClearance" : {
"type" : "boolean",
"description" : "Indicates whether the shipment is subject to export customs clearance",
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kuehne-nagel/refs/heads/main/openapi/kuehne-nagel-booking-air-v2-openapi.json