v1.0.0 DCSA 3.0.0
Request Access

Track & Trace Events

Download OpenAPI Document

Retrieve Track & Trace Events based on DCSA Interface standard v 2.2.

Overview

Returns all events filtered by the queryParameters. This endpoint requires at least one of the following input parameters:

  • bookingReference — Booking reference (HBL number).
  • equipmentReference — Will filter by the unique identifier for the equipment, which should follow the BIC ISO Container Identification Number.
Scope: trackntrace:read

Getting started

Access to this API is limited to approved customers currently doing business with Airlift.

Getting Started Guide

OAuth 2.0

Bearer Token

Get an OAuth 2.0 access token using client credentials before calling the APIs.

Open Authorization Guide

Find events.

Returns all events filtered by the queryParameters. This endpoint requires at least one of the following input parameters:

Query Parameters

bookingReference string[a-zA-Z0-9]{9}
Booking reference (HBL number).
equipmentReference stringmax length: 15
Will filter by the unique identifier for the equipment, which should follow the BIC ISO Container Identification Number.

Headers

Authorization stringBearer YOUR_TOKEN
Bearer token issued for your registered application must be provided with every request.

Responses

  • 200Successful operation
  • 400Bad request; the request is unacceptable often due to a missing or invalid parameter.
  • 401The client cannot be authenticated by the system.
  • 403The client does not have permissions to access this endpoint.
  • 404The requested resource cannot be found.
  • 500Internal server error.

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

Rate limits

Per Hour Per Minute Burst
400060100

Release Notes