Events

POST /events is a carrier-facing endpoint: as an API consumer you never need to call it. If you're subscribing to shipments and receiving tracking data, your events arrive on your webhook or through a pull; this page is not part of your integration.

It exists for the other side of the platform: carriers delivering tracking data to us. If a carrier's integration is event-driven (they push rather than being polled), or they're not on our supported carrier list yet, they can post DCSA-standard events straight into the platform here. Those events then reach subscribers exactly as polled events do; consumers can't tell the difference.

The rest of this page documents the payloads a carrier sends, which are also the same DCSA shapes consumers receive, so it doubles as a field reference for everyone.

The event standard

All tracking data, whatever its source format (DCSA 1.2/2.2, EDIFACT, or a carrier-specific feed), is normalized to DCSA EVENT_DOMAIN 2.0.2, so consumers only ever parse one event shape. There are two event shapes: equipment events and transport events. POST /events accepts either; the service infers which from eventType. See Post an equipment or transport tracking event for the full schema, including documentReferences (booking/bill-of-lading cross-references) and validation errors.

Equipment events

An equipment event describes something happening to a specific container: loaded, discharged, gated in/out, stuffed, stripped, picked up, dropped off, inspected, sealed, or removed.

{
  "eventType": "EQUIPMENT",
  "eventClassifierCode": "ACT",
  "eventDateTime": "2023-06-15T10:30:00Z",
  "equipmentEventTypeCode": "LOAD",
  "equipmentReference": "ABCU1234567",
  "emptyIndicatorCode": "LADEN",
  "eventLocation": {
    "locationName": "Port of Hamburg",
    "UNLocationCode": "DEHAM"
  },
  "transportCall": {
    "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" }
  }
}

Key fields:

Field	Notes
eventClassifierCode	ACT (actual), PLN (planned), or EST (estimated)
equipmentEventTypeCode	LOAD, DISC, GTIN, GTOT, STUF, STRP, PICK, DROP, INSP, RSEA, RMVD
equipmentReference	The container number
eventLocation	Where the event happened; see DCSA location below
transportCall	Vessel, voyage, and location context; see below

Transport events

A transport event describes a vessel arriving at or departing from a transport call (a scheduled vessel call at a location). Unlike equipment events, location lives in transportCall.location, not a top-level eventLocation.

{
  "eventType": "TRANSPORT",
  "eventClassifierCode": "ACT",
  "eventDateTime": "2023-06-16T04:00:00Z",
  "transportEventTypeCode": "ARRI",
  "equipmentReference": "ABCU1234567",
  "transportCall": {
    "UNLocationCode": "DEHAM",
    "carrierVoyageNumber": "123W",
    "vessel": { "vesselIMONumber": "9321483", "vesselName": "MSC GULSUN" }
  }
}

transportEventTypeCode is ARRI (arrival) or DEPA (departure).

Locations

Both event shapes reference a DCSA location object: a UN/LOCODE, a facility code, coordinates, and/or a free-form address, wherever the source data provides them:

{
  "locationName": "Port of Hamburg",
  "UNLocationCode": "DEHAM",
  "latitude": "53.5459",
  "longitude": "9.9689"
}