Ocean Booking Service API

POST /bookings returns bookings for the authenticated account as a list, 25 at a time by default, each in the same DCSA booking record the single-booking endpoint returns. Pass limit and offset to page, and static_filter to restrict the list to a status such as inprogress. It is the endpoint to call on a schedule when an ERP or TMS mirrors the whole book of open shipments instead of asking for one booking at a time.

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

Parameters

Query parameter	Meaning	Example
`limit`	Maximum number of bookings in the response.	`25`
`offset`	Zero-based index of the first booking to return.	`0`
`static_filter`	Named status filter; omit for all bookings.	`inprogress`

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.

Request body

{ "static_filter": "inprogress", "limit": 25, "offset": 0 }

Example request

curl -X POST 'https://api.airliftusa.com/api/v1/api-service/external/bookings' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"static_filter":"inprogress","limit":25,"offset":0}'

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, "commodities": [{ "commodityType": "Dry cargo, Freight all kinds" }] }
    ],
    "cargoMovementTypeAtOrigin": "FCL",
    "incoTerms": "EXW",
    "freightPaymentTermCode": "PRE"
  }
]

The response is a JSON array of booking records; each element has the same fields as GET /booking.
Page with limit and offset until a page comes back shorter than limit.

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

Why is this a POST?

The filters travel in a JSON body as well as the query string, which keeps longer filter sets off the URL. The call reads data and changes nothing.

What does static_filter accept?

Named filters such as inprogress. Leave it out to list every booking the account can see.

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 list retrieval.

Server

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

Authentication

Bearer TokenOAuth 2.0

Bearer token for authentication

Bearer Token

Operations

POST/bookings

Client Libraries

Request

POST/bookingscURL

curl 'https://api.airliftusa.com/api/v1/api-service/external/bookings?limit=25' \
  --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 Service API

Parameters

Request body

Example request

Example response (200)

Frequently asked questions

Why is this a POST?

What does static_filter accept?

Other endpoints

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

Models

Release Notes

We value your privacy