Ocean Booking API

GET /booking returns the booking record for one Airlift booking reference, as the DCSA Booking standard lays it out: the booking agent and contacts, the requested equipment and commodities with gross weight, the port of loading and port of discharge, the vessel and voyage, the expected departure and arrival dates, the Incoterms and the freight and charges payment terms. It is the read side of a booking an importer’s ERP or TMS keeps in sync after Airlift confirms it.

GEThttps://api.airliftusa.com/api/v1/api-service/external/booking · scope bookings:read · DCSA 3.0.0 · reference updated 2025-01-06

Parameters

Query parameter	Meaning	Example
`bookingReference`	The booking reference Airlift issued for the shipment.	`AIRLAMD132196`

Send Authorization: Bearer <token> with every request. The token comes from the OAuth 2.0 client credentials flow and must carry the bookings:read scope.

Example request

curl 'https://api.airliftusa.com/api/v1/api-service/external/booking?bookingReference=AIRLAMD132196' \
  --header 'Authorization: Bearer YOUR_TOKEN'

Example response (200)

{
  "carrierServiceCode": "TA1",
  "carrierExportVoyageNumber": "403W",
  "vessel": { "name": "MAERSK IOWA", "vesselIMONumber": "9298686" },
  "expectedDepartureDate": "2024-01-20",
  "expectedArrivalDate": "2024-02-14",
  "shipmentLocations": [
    { "locationTypeCode": "POL", "location": { "UNLocationCode": "DEBRV", "locationName": "Bremerhaven" } },
    { "locationTypeCode": "POD", "location": { "UNLocationCode": "USORF", "locationName": "Norfolk" } }
  ],
  "requestedEquipments": [
    {
      "ISOEquipmentCode": "42G1",
      "units": 3,
      "isShipperOwned": false,
      "commodities": [
        { "commodityType": "Dry cargo, Freight all kinds", "cargoGrossWeight": { "value": 36000, "unit": "KGM" } }
      ]
    }
  ],
  "cargoMovementTypeAtOrigin": "FCL",
  "cargoMovementTypeAtDestination": "FCL",
  "receiptTypeAtOrigin": "CY",
  "deliveryTypeAtDestination": "CY",
  "incoTerms": "EXW",
  "freightPaymentTermCode": "PRE",
  "serviceContractReference": "HHL51800000",
  "contractQuotationReference": "HHL1401",
  "references": [{ "type": "CR", "value": "KN-00103004" }],
  "documentParties": {
    "bookingAgent": { "partyName": "KN Bremerhaven", "address": { "city": "Bremerhaven", "countryCode": "DE" } }
  }
}

shipmentLocations carries the port of loading (POL) and port of discharge (POD) as UN/LOCODEs.
requestedEquipments lists each container type by ISO equipment code with the number of units and the commodities inside.
The payment term codes (PRE prepaid, COL collect) apply to freight, origin charges and destination charges separately.

Other status codes: 400 missing or invalid parameter, 401 token missing or expired, 403 scope not granted, 404 nothing matches the reference, 500 server error. Limits are 60 requests a minute and 4,000 an hour per consumer, reported in the X-RateLimit-* headers.

Frequently asked questions

What is the booking reference?

The reference Airlift issues when it confirms a booking, for example AIRLAMD132196. It is the same reference printed on the booking confirmation and used by the tracking and documents endpoints.

How do I list bookings rather than fetch one?

Use the Ocean Booking Service endpoint, POST /bookings, which pages through all bookings for your account and accepts a status filter.

Other endpoints

Need access? Register your application in the developer portal; the API is open to approved Airlift customers.

Full reference: models, response schemas, client snippets and a live console

Everything the guide above leaves out: every response schema, the request in cURL, Node.js, Python and Go, the environment and token panel, the OpenAPI download and the Swagger console.

Download OpenAPI Document

Models

BookingModel

object23 fields

Description

Ocean booking details.

Fields

cargoMovementTypeAtDestination

string

Cargo movement type at destination.

cargoMovementTypeAtOrigin

string

Cargo movement type at origin.

carrierExportVoyageNumber

string

Carrier export voyage number.

carrierServiceCode

string

Carrier service code.

contractQuotationReference

string

Contract quotation reference.

deliveryTypeAtDestination

string

Delivery type at destination.

destinationChargesPaymentTerm

object

Destination charges payment terms.

documentParties

object

Document parties in the booking.

expectedArrivalDate

string

Estimated arrival date at the port of discharge (revised ETA if available, otherwise the original ETA).

expectedDepartureDate

string

Expected departure date.

freightPaymentTermCode

string

Freight payment term code.

incoTerms

string

Incoterms.

isEquipmentSubstitutionAllowed

boolean

Indicates if equipment substitution is allowed.

isExportDeclarationRequired

boolean

Indicates if export declaration is required.

isPartialLoadAllowed

boolean

Indicates if partial load is allowed.

originChargesPaymentTerm

object

Origin charges payment terms.

partyContactDetails

array

Top-level contact details for the booking.

receiptTypeAtOrigin

string

Receipt type at origin.

references

array

Reference pairs for the booking.

requestedEquipments

array

Requested equipment details.

serviceContractReference

string

Service contract reference.

shipmentLocations

array

Shipment locations for the booking.

vessel

object

Vessel details.

ErrorResponseModel

object1 fields

Fields

error

object

Properties

code

string

Error code

message

string

Human-readable error message

Release Notes

Version	Date	Notes
1.0.0	2025-01-06	Initial release of ocean booking details.

Server

https://api.airliftusa.com/api/v1/api-service/externalEnvironment

Authentication

Bearer TokenOAuth 2.0

Bearer token for authentication

Bearer Token

Operations

GET/booking

Client Libraries

Request

GET/bookingcURL

curl 'https://api.airliftusa.com/api/v1/api-service/external/booking?bookingReference=AIRLAMD132196' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "cargoMovementTypeAtDestination": "FCL",
  "cargoMovementTypeAtOrigin": "FCL",
  "carrierExportVoyageNumber": "403W",
  "carrierServiceCode": "TA1",
  "contractQuotationReference": "HHL1401",
  "deliveryTypeAtDestination": "CY",
  "destinationChargesPaymentTerm": {
    "haulageChargesPaymentTermCode": "COL",
    "otherChargesPaymentTermCode": "PRE",
    "portChargesPaymentTermCode": "PRE"
  },
  "documentParties": {
    "bookingAgent": {
      "address": {
        "city": "Bremerhaven",
        "countryCode": "DE",
        "postCode": "27568",
        "street": "Amerikaring",
        "streetNumber": "40"
      },
      "partyContactDetails": [
        {
          "name": "Export operations department",
          "phone": "+49 471 945410"
        }
      ],
      "partyName": "KN Bremerhaven"
    }
  },
  "expectedArrivalDate": "2024-02-14",
  "expectedDepartureDate": "2024-01-20",
  "freightPaymentTermCode": "PRE",
  "incoTerms": "EXW",
  "isEquipmentSubstitutionAllowed": false,
  "isExportDeclarationRequired": false,
  "isPartialLoadAllowed": false,
  "originChargesPaymentTerm": {
    "haulageChargesPaymentTermCode": "PRE",
    "portChargesPaymentTermCode": "PRE"
  },
  "partyContactDetails": [
    {
      "name": "Diane",
      "phone": "+49 471 945410"
    }
  ],
  "receiptTypeAtOrigin": "CY",
  "references": [
    {
      "type": "CR",
      "value": "KN-00103004"
    }
  ],
  "requestedEquipments": [
    {
      "ISOEquipmentCode": "42G1",
      "commodities": [
        {
          "cargoGrossWeight": {
            "unit": "KGM",
            "value": 36000
          },
          "commodityType": "Dry cargo, Freight all kinds"
        }
      ],
      "isShipperOwned": false,
      "units": 3
    }
  ],
  "serviceContractReference": "HHL51800000",
  "shipmentLocations": [
    {
      "location": {
        "UNLocationCode": "DEBRV",
        "locationName": "Bremerhaven"
      },
      "locationTypeCode": "POL"
    },
    {
      "location": {
        "UNLocationCode": "USORF",
        "locationName": "Norfolk"
      },
      "locationTypeCode": "POD"
    }
  ],
  "vessel": {
    "name": "MAERSK IOWA",
    "vesselIMONumber": "9298686"
  }
}

Ocean Booking API

Parameters

Example request

Example response (200)

Frequently asked questions

What is the booking reference?

How do I list bookings rather than fetch one?

Other endpoints

Full reference: models, response schemas, client snippets and a live console

Models

Release Notes

We value your privacy