Track and Trace Events API

GET /trackntrace returns the tracking events recorded for an Airlift ocean shipment: shipment events (booking confirmed, documents issued), equipment events (gate in, loaded, discharged, gate out, empty returned) and transport events (vessel departure and arrival), plus the inland and rail legs that follow discharge. Filter by the booking reference (the HBL number) or by the container number; at least one is required. Events follow the DCSA Track and Trace interface, so a consumer written for a DCSA-aligned carrier reads them without a custom mapping.

GEThttps://api.airliftusa.com/api/v1/api-service/external/trackntrace · scope trackntrace:read · DCSA 3.0.0 · reference updated 2025-03-31

Parameters

Query parameterMeaningExample
bookingReferenceBooking reference (the HBL number). Nine alphanumeric characters.AIRLCHN133184
equipmentReferenceContainer number in the BIC ISO format, up to 15 characters.CMAU1234567

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

Example request

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

Example response (200)

{
  "success": true,
  "statusCode": 200,
  "data": [
    {
      "eventID": "lMZQf2mGf4q4jF8m2QG7F8C5iY7sH9TgJ0l5vH8tZ8c",
      "eventType": "EQUIPMENT",
      "eventClassifierCode": "ACT",
      "eventDateTime": "2019-11-10T07:41:00+08:00",
      "eventCreatedDateTime": "2021-01-07T14:12:56Z",
      "equipmentReference": "CMAU1234567",
      "ISOEquipmentCode": "22G1",
      "transportEventTypeCode": "GATI",
      "eventLocation": { "UNLocationCode": "USNYC", "locationName": "Port of New York" },
      "transportCall": {
        "UNLocationCode": "USNYC",
        "facilityTypeCode": "POTE",
        "modeOfTransport": "VESSEL",
        "carrierServiceCode": "AS1",
        "exportVoyageNumber": "123A",
        "vessel": { "vesselIMONumber": "9876543", "vesselName": "Demo Vessel" }
      }
    },
    {
      "eventID": "j5A5tC2a1W5W4YV4K9O2k2Ih9J7GfC0l3H1bP2oB4KQ",
      "eventType": "TRANSPORT",
      "eventClassifierCode": "ACT",
      "eventDateTime": "2019-11-12T07:41:00+08:00",
      "transportEventTypeCode": "DEPA",
      "eventLocation": { "UNLocationCode": "USNYC", "locationName": "Port of New York" }
    }
  ],
  "metadata": { "timestamp": "2025-06-19T11:00:11Z" }
}
  • eventType is SHIPMENT, EQUIPMENT or TRANSPORT; eventClassifierCode is ACT for an actual event, PLN for a planned one and EST for an estimate.
  • Equipment events carry equipmentReference (the container) and ISOEquipmentCode; transport events carry the transportCall with the vessel, voyage and UN/LOCODE.
  • eventDateTime is when the event happened at the location, with its local offset; eventCreatedDateTime is when it reached the Airlift system.

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

Which identifiers can I track by?

The booking reference (Airlift house bill number) or the container number. Send at least one; sending both narrows the result to that container on that booking.

Is this the DCSA Track and Trace format?

Yes. The product is published as DCSA 3.0.0 compliant and the event shape follows the DCSA Track and Trace interface, so the same consumer can read Airlift events and events from DCSA-aligned carriers.

Does it cover rail and trucking after discharge?

Yes. Inland and rail transport legs that belong to the booking are returned as events alongside the ocean legs.

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

AddressModel
object5 fields
Fields
city
string
countryCode
string
postCode
string
street
string
streetNumber
string
DocumentReferencesModel
array object[]2 fields
Description

An optional list of key-value (documentReferenceType-documentReferenceValue) pairs representing links to objects relevant to the event.

Fields
documentReferenceType
enum

Describes where the documentReferenceValue is pointing to.

  • BKG (Booking)
  • TRD (Transport Document)
documentReferenceValue
string

The value of the identifier the documentReferenceType is describing.

EquipmentEventModel
object11 fields
Description

Base event fields common to all event types.

Fields
eventClassifierCode
string

Classifier for the event (e.g., ACT, EST, PLN).

eventCreatedDateTime
string

Date and time when the event was recorded.

eventDateTime
string

Date and time when the event occurred.

eventID
string

Unique identifier of the event.

eventLocation
object

Event location information based on UN/LOCODE.

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Human-readable location name.

longitude
string

Longitude of the location.

eventType
enum

Event category.

  • SHIPMENT
  • TRANSPORT
  • EQUIPMENT
transportCall
object

Transport call details where the event occurred.

Properties
UNLocationCode
string

UN/LOCODE of the transport call.

carrierServiceCode
string

Carrier service code.

exportVoyageNumber
string

Export voyage number.

facilityTypeCode
string

Facility type code (e.g., POTE, DEPO).

importVoyageNumber
string

Import voyage number.

location
object

Location information (UN/LOCODE with optional facility details).

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Location name.

longitude
string

Longitude of the location.

modeOfTransport
string

Mode of transport (e.g., VESSEL, RAIL, TRUCK).

transportCallSequenceNumber
integer

Sequence number of the transport call in the voyage.

vessel
object
Properties
vesselCallSignNumber
string

A unique alphanumeric identity assigned to the vessel by the ITU.

vesselFlag
string

The ISO 3166 two-letter country code.

vesselIMONumber
integer

The unique reference for a registered Vessel (IMO number).

vesselName
string

The name of the Vessel given by the operator and registered with IMO.

vesselOperatorCarrierCode
string

The carrier in charge of the vessel operation.

vesselOperatorCarrierCodeListProvider
enum

Identifies the code list provider used for the operator and partner carrierCodes.

  • SMDG
  • NMFTA
ISOEquipmentCode
string

ISO equipment code (e.g., 22G1).

equipmentEventTypeCode
string

Equipment event type code (e.g., LOAD, DISC, GTIN).

equipmentReference
string

Equipment reference (container number).

transportEventTypeCode
string

Transport event type code if reported for equipment events.

ErrorResponseModel
object4 fields
Fields
details
object

Optional error details for diagnostics.

error
string

Human-readable error message.

statusCode
integer

HTTP status code for the error response.

statusMessage
string

HTTP status text.

EventModel
object7 fields
Description

Base event fields common to all event types.

Fields
eventClassifierCode
string

Classifier for the event (e.g., ACT, EST, PLN).

eventCreatedDateTime
string

Date and time when the event was recorded.

eventDateTime
string

Date and time when the event occurred.

eventID
string

Unique identifier of the event.

eventLocation
object

Event location information based on UN/LOCODE.

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Human-readable location name.

longitude
string

Longitude of the location.

eventType
enum

Event category.

  • SHIPMENT
  • TRANSPORT
  • EQUIPMENT
transportCall
object

Transport call details where the event occurred.

Properties
UNLocationCode
string

UN/LOCODE of the transport call.

carrierServiceCode
string

Carrier service code.

exportVoyageNumber
string

Export voyage number.

facilityTypeCode
string

Facility type code (e.g., POTE, DEPO).

importVoyageNumber
string

Import voyage number.

location
object

Location information (UN/LOCODE with optional facility details).

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Location name.

longitude
string

Longitude of the location.

modeOfTransport
string

Mode of transport (e.g., VESSEL, RAIL, TRUCK).

transportCallSequenceNumber
integer

Sequence number of the transport call in the voyage.

vessel
object
Properties
vesselCallSignNumber
string

A unique alphanumeric identity assigned to the vessel by the ITU.

vesselFlag
string

The ISO 3166 two-letter country code.

vesselIMONumber
integer

The unique reference for a registered Vessel (IMO number).

vesselName
string

The name of the Vessel given by the operator and registered with IMO.

vesselOperatorCarrierCode
string

The carrier in charge of the vessel operation.

vesselOperatorCarrierCodeListProvider
enum

Identifies the code list provider used for the operator and partner carrierCodes.

  • SMDG
  • NMFTA
EventLocationModel
object6 fields
Description

Event location information based on UN/LOCODE.

Fields
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Human-readable location name.

longitude
string

Longitude of the location.

LocationModel
object6 fields
Description

Location information (UN/LOCODE with optional facility details).

Fields
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Location name.

longitude
string

Longitude of the location.

ResponseMetadataModel
object2 fields
Description

Response metadata such as timestamps and paging information.

Fields
requestId
string

Optional unique request identifier for troubleshooting.

timestamp
string

Server timestamp when the response was generated.

SealModel
object0 fields
Fields
No properties defined.
ShipmentEventModel
object12 fields
Description

Base event fields common to all event types.

Fields
eventClassifierCode
string

Classifier for the event (e.g., ACT, EST, PLN).

eventCreatedDateTime
string

Date and time when the event was recorded.

eventDateTime
string

Date and time when the event occurred.

eventID
string

Unique identifier of the event.

eventLocation
object

Event location information based on UN/LOCODE.

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Human-readable location name.

longitude
string

Longitude of the location.

eventType
enum

Event category.

  • SHIPMENT
  • TRANSPORT
  • EQUIPMENT
transportCall
object

Transport call details where the event occurred.

Properties
UNLocationCode
string

UN/LOCODE of the transport call.

carrierServiceCode
string

Carrier service code.

exportVoyageNumber
string

Export voyage number.

facilityTypeCode
string

Facility type code (e.g., POTE, DEPO).

importVoyageNumber
string

Import voyage number.

location
object

Location information (UN/LOCODE with optional facility details).

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Location name.

longitude
string

Longitude of the location.

modeOfTransport
string

Mode of transport (e.g., VESSEL, RAIL, TRUCK).

transportCallSequenceNumber
integer

Sequence number of the transport call in the voyage.

vessel
object
Properties
vesselCallSignNumber
string

A unique alphanumeric identity assigned to the vessel by the ITU.

vesselFlag
string

The ISO 3166 two-letter country code.

vesselIMONumber
integer

The unique reference for a registered Vessel (IMO number).

vesselName
string

The name of the Vessel given by the operator and registered with IMO.

vesselOperatorCarrierCode
string

The carrier in charge of the vessel operation.

vesselOperatorCarrierCodeListProvider
enum

Identifies the code list provider used for the operator and partner carrierCodes.

  • SMDG
  • NMFTA
documentID
string

Identifier for the document.

documentReference
array object[]

An optional list of key-value (documentReferenceType-documentReferenceValue) pairs representing links to objects relevant to the event.

Properties
documentReferenceType
enum

Describes where the documentReferenceValue is pointing to.

  • BKG (Booking)
  • TRD (Transport Document)
documentReferenceValue
string

The value of the identifier the documentReferenceType is describing.

documentTypeCode
string

Document type code (e.g., BKG, TRD).

reason
string

Optional reason for the event.

shipmentEventTypeCode
string

Shipment event type code (e.g., RECE, CONF).

TrackingEventsResponseModel
object5 fields
Description

Standard response wrapper for Track & Trace events.

Fields
data
array<oneOf>items: oneOf

List of events matching the filter criteria.

metadata
object

Response metadata such as timestamps and paging information.

Properties
requestId
string

Optional unique request identifier for troubleshooting.

timestamp
string

Server timestamp when the response was generated.

statusCode
integer

HTTP status code for the response.

statusMessage
string

HTTP status text.

success
boolean

Indicates whether the request was successful.

TransportCallModel
object9 fields
Description

Transport call details where the event occurred.

Fields
UNLocationCode
string

UN/LOCODE of the transport call.

carrierServiceCode
string

Carrier service code.

exportVoyageNumber
string

Export voyage number.

facilityTypeCode
string

Facility type code (e.g., POTE, DEPO).

importVoyageNumber
string

Import voyage number.

location
object

Location information (UN/LOCODE with optional facility details).

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Location name.

longitude
string

Longitude of the location.

modeOfTransport
string

Mode of transport (e.g., VESSEL, RAIL, TRUCK).

transportCallSequenceNumber
integer

Sequence number of the transport call in the voyage.

vessel
object
Properties
vesselCallSignNumber
string

A unique alphanumeric identity assigned to the vessel by the ITU.

vesselFlag
string

The ISO 3166 two-letter country code.

vesselIMONumber
integer

The unique reference for a registered Vessel (IMO number).

vesselName
string

The name of the Vessel given by the operator and registered with IMO.

vesselOperatorCarrierCode
string

The carrier in charge of the vessel operation.

vesselOperatorCarrierCodeListProvider
enum

Identifies the code list provider used for the operator and partner carrierCodes.

  • SMDG
  • NMFTA
TransportEventModel
object8 fields
Description

Base event fields common to all event types.

Fields
eventClassifierCode
string

Classifier for the event (e.g., ACT, EST, PLN).

eventCreatedDateTime
string

Date and time when the event was recorded.

eventDateTime
string

Date and time when the event occurred.

eventID
string

Unique identifier of the event.

eventLocation
object

Event location information based on UN/LOCODE.

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Human-readable location name.

longitude
string

Longitude of the location.

eventType
enum

Event category.

  • SHIPMENT
  • TRANSPORT
  • EQUIPMENT
transportCall
object

Transport call details where the event occurred.

Properties
UNLocationCode
string

UN/LOCODE of the transport call.

carrierServiceCode
string

Carrier service code.

exportVoyageNumber
string

Export voyage number.

facilityTypeCode
string

Facility type code (e.g., POTE, DEPO).

importVoyageNumber
string

Import voyage number.

location
object

Location information (UN/LOCODE with optional facility details).

Properties
UNLocationCode
string

UN/LOCODE of the location.

facilityCode
string

Facility code at the location (if applicable).

facilityCodeListProvider
string

Code list provider for the facility code.

latitude
string

Latitude of the location.

locationName
string

Location name.

longitude
string

Longitude of the location.

modeOfTransport
string

Mode of transport (e.g., VESSEL, RAIL, TRUCK).

transportCallSequenceNumber
integer

Sequence number of the transport call in the voyage.

vessel
object
Properties
vesselCallSignNumber
string

A unique alphanumeric identity assigned to the vessel by the ITU.

vesselFlag
string

The ISO 3166 two-letter country code.

vesselIMONumber
integer

The unique reference for a registered Vessel (IMO number).

vesselName
string

The name of the Vessel given by the operator and registered with IMO.

vesselOperatorCarrierCode
string

The carrier in charge of the vessel operation.

vesselOperatorCarrierCodeListProvider
enum

Identifies the code list provider used for the operator and partner carrierCodes.

  • SMDG
  • NMFTA
transportEventTypeCode
string

Transport event type code (e.g., DEPA, ARRI).

VesselModel
object6 fields
Fields
vesselCallSignNumber
string

A unique alphanumeric identity assigned to the vessel by the ITU.

vesselFlag
string

The ISO 3166 two-letter country code.

vesselIMONumber
integer

The unique reference for a registered Vessel (IMO number).

vesselName
string

The name of the Vessel given by the operator and registered with IMO.

vesselOperatorCarrierCode
string

The carrier in charge of the vessel operation.

vesselOperatorCarrierCodeListProvider
enum

Identifies the code list provider used for the operator and partner carrierCodes.

  • SMDG
  • NMFTA

We value your privacy

We use cookies to keep our portal working, measure site usage, and analyse the businesses that visit us. Under U.S. state privacy laws, the data we share with our analytics, advertising and sales partners is considered a “sale” or “sharing” of personal data.