Data Elements & Enumerations (DCSA-aligned)

This page documents the coded values used throughout the FreightLens Track & Trace API.
FreightLens normalizes every carrier's data into these DCSA-aligned code lists, so the same
codes mean the same thing regardless of the underlying carrier. Codes marked with a DCSA
lineage follow the DCSA Track & Trace standard; a few (exceptions, trigger types) are
FreightLens extensions layered on top.

Event model overview

Every shipment carries three categories of event. Each event has an eventClassifierCode
telling you how firm its timestamp is, and a type code specific to its category.

Event group	Where it appears	Type field
Shipment events	`shipmentTracking.shipmentEvents[]`	`shipmentEventTypeCode`
Transport events	`shipmentTracking.transportEvents[]`	`transportEventTypeCode`
Equipment events	each container's `latestEvent` and `eventHistory[]`	`equipmentEventTypeCode`

Event classifier — `eventClassifierCode`

Tells you whether an event has happened, is estimated, or is planned. This is the single
most important field for interpreting a timeline: when a code moves from EST/PLN to
ACT, the milestone has actually occurred.

Code	Meaning	Notes
`ACT`	Actual	The event has happened. The timestamp is confirmed.
`EST`	Estimated	A forward-looking prediction. The timestamp may still move.
`PLN`	Planned	Taken from the carrier's schedule; not yet estimated or actualized.

Shipment event types — `shipmentEventTypeCode`

Document and booking milestones.

Code	Meaning
`RECE`	Received — booking request received.
`DRFT`	Drafted — document drafted.
`PENA`	Pending approval.
`CONF`	Confirmed — booking confirmed by the carrier.
`APPR`	Approved.
`SUBM`	Submitted.
`ISSU`	Issued — e.g. Bill of Lading issued.
`SURR`	Surrendered — B/L surrendered.
`REJE`	Rejected.

Transport event types — `transportEventTypeCode`

Vessel movements at a port call.

Code	Meaning
`ARRI`	Arrived — vessel arrived at the port call.
`DEPA`	Departed — vessel departed the port call.

Equipment event types — `equipmentEventTypeCode`

Container movements.

Code	Meaning
`GTIN`	Gate in — container entered a facility.
`GTOT`	Gate out — container left a facility.
`LOAD`	Loaded — container loaded onto a vessel.
`DISC`	Discharged — container discharged from a vessel.
`STUF`	Stuffed — cargo stuffed into the container.
`STRP`	Stripped — cargo stripped from the container.
`PICK`	Picked up.
`DROP`	Dropped off.
`INSP`	Inspected.
`RSEA`	Resealed.
`RMVD`	Removed.

Empty indicator — `emptyIndicatorCode`

Code	Meaning
`LADEN`	The container holds cargo.
`EMPTY`	The container is empty.

Location & transport attributes

Mode of transport — `modeOfTransport`

Code	Meaning
`VESSEL`	Ocean vessel.
`BARGE`	Barge / feeder.
`RAIL`	Rail.
`TRUCK`	Road / truck.

Facility type — `facilityTypeCode`

Code	Meaning
`POTE`	Port terminal.
`DEPO`	Container depot.
`INTE`	Inland terminal.
`COFS`	Container freight station.
`OFFD`	Off-dock storage.

Facility code-list provider — `facilityCodeListProvider`

Identifies which coding scheme a facilityCode belongs to.

Code	Provider
`BIC`	Bureau International des Containers.
`SMDG`	SMDG terminal code list.

Location codes

Every location (portOfLoading, portOfDischarge, placeOfReceipt, placeOfDelivery,
and event locations) carries a unLocationCode — the five-character UN/LOCODE (e.g.
USNYC = New York, VNVUT = Vung Tau) — alongside a human-readable locationName.

Service type — `serviceType`

The scope of carriage FreightLens is tracking.

Code	Meaning
`PORT_TO_PORT`	Origin port to destination port.
`PORT_TO_DOOR`	Origin port to consignee door.
`DOOR_TO_PORT`	Shipper door to destination port.
`DOOR_TO_DOOR`	Shipper door to consignee door.

Transmission attributes

Trigger type — `transmissionHeader.triggerType`

Why a transmission was generated. Read-only GET lookups always return
MANUAL_TRIGGER; the remaining values apply to roadmap webhook delivery.

Code	Meaning
`MANUAL_TRIGGER`	A full current snapshot — what `GET /v2/shipments` returns.
`SCHEDULED_TRIGGER`	A periodic refresh of the shipment state (webhook, roadmap).
`EVENT_TRIGGER`	A new milestone arrived (webhook, roadmap).
`EXCEPTION_DETECTED`	A new exception was raised (webhook, roadmap).
`EXCEPTION_RESOLVED`	A previously raised exception cleared (webhook, roadmap).

Exceptions (FreightLens extension)

Exceptions are a FreightLens layer on top of DCSA — DCSA does not define them. They appear
in shipmentTracking.exceptions[] when triggerType is EXCEPTION_DETECTED or
EXCEPTION_RESOLVED.

Exception category — `exceptionCategory`

Code	Meaning	In the app
`SCHEDULE`	Timing problems — ETA/ETD slips, missed connections.	Amber
`OPERATIONAL`	Action-required problems — rollovers, demurrage/detention risk, holds.	Red

Exception type — `exceptionType`

Code	Category	Meaning
`ETA_DELAY`	SCHEDULE	Estimated arrival pushed later.
`ETD_DELAY`	SCHEDULE	Estimated departure pushed later.
`MISSED_CONNECTION`	SCHEDULE	A transshipment connection was missed.
`VESSEL_CHANGE`	SCHEDULE	The assigned vessel changed.
`ROUTE_CHANGE`	SCHEDULE	The routing changed.
`ROLLOVER`	OPERATIONAL	Container rolled to a later sailing.
`DEMURRAGE_RISK`	OPERATIONAL	Container at risk of demurrage charges.
`DETENTION_RISK`	OPERATIONAL	Container at risk of detention charges.
`HOLD`	OPERATIONAL	A hold (customs, carrier, or other) is in place.

Severity — `severity`

Code	Meaning
`WARNING`	Attention advised; not yet critical.
`CRITICAL`	Immediate attention required.

Status — `status`

Code	Meaning
`DETECTED`	The exception is currently active.
`RESOLVED`	The exception has cleared.

Resolution type — `resolutionType` (present when `status` is `RESOLVED`)

Code	Meaning
`SCHEDULE_RECOVERED`	The carrier recovered the schedule.
`REBOOKED`	The shipment was rebooked onto another sailing.
`EVENT_ACTUALIZED`	The awaited event actually occurred, clearing the risk.
`MANUAL_CLEAR`	Cleared manually by an operator.

Schema version 1.2. New codes may be added over time; treat unknown codes defensively
rather than assuming the list is fixed.

Data Elements & Enumerations (DCSA-aligned)

Event model overview#

Event classifier — eventClassifierCode#

Shipment event types — shipmentEventTypeCode#

Transport event types — transportEventTypeCode#

Equipment event types — equipmentEventTypeCode#

Empty indicator — emptyIndicatorCode#

Location & transport attributes#

Mode of transport — modeOfTransport#

Facility type — facilityTypeCode#

Facility code-list provider — facilityCodeListProvider#

Location codes#

Service type — serviceType#

Transmission attributes#

Trigger type — transmissionHeader.triggerType#

Exceptions (FreightLens extension)#

Exception category — exceptionCategory#

Exception type — exceptionType#

Severity — severity#

Status — status#

Resolution type — resolutionType (present when status is RESOLVED)#