Skip to content
Navo24Navo24
GETAPI keyCounts as a call

Look up by identifier

GETapi.navo24.com/v1/tracking/containers/lookup/{identifier}

Resolve a container number, bill of lading or booking straight to its record, without holding the UUID. Handy when your own system keys on the carrier reference. One thing to know before you loop over it: an identifier you are not tracking yet is registered on the spot, which consumes a shipment slot exactly as an add would, and the call answers 202 with TRACKING_IN_PROGRESS while the carrier is asked.

Counted: REST: 1 call per keyed request, whatever the route answers; a quota refusal is not counted. MCP: 10 Navo Tokens when the answer carries data; free on 202 STILL_RESOLVING, 404 REFERENCE_NOT_RESOLVABLE and 404 AUTO_CANT_FIND_INFO. A reference new to us is added (250). See what counts as a successful request.

Path parameters

identifierstringrequired

The container number, bill of lading or booking you tracked.

Response schema

211 fields

Generated from the OpenAPI spec. Nested exactly as the JSON is. Open a branch to read its fields; hover a name for the full dot-path.

okboolean

Whether the request succeeded.

api_versionstring

The response contract this build answers, as a date.

dataobject

The payload.

idstring

Stable identifier for the record.

container_numberstring

The container number, or null when the record was tracked by a bill of lading or booking that has not yet resolved to a box.

bl_numberstring | null

The bill of lading, or null when the record was not tracked by one.

identifierstring

The container number, bill of lading or booking this record tracks.

identifier_typestring

What the identifier is.

booking_numberstring | null

The booking reference, or null when the record was not tracked by one.

container_sizestring

Equipment size, for example 40HC.

equipment_typestring

Equipment family as the carrier names it.

iso_type_codestring

The type half of the ISO 6346 code (G1 for a general-purpose box, R1 for a reefer).

child_containersarray | null

The boxes a bill of lading or booking resolves to, each with its own timeline and its own status (with status_source: tracked when your organisation also tracks the box on its own line, line when read from the events the line filed for that box on this document, document when the document holds no per-box events and none of its events names another box, so the box shows the document's own status, which can be a stage read from the vessel's AIS, such as at_berth or at_anchor; both null when none has reported one).

child_containers[]object
numberstring

Container number of the box, or TBA for a group of boxes the line has not numbered yet.

iso_codestring | null

ISO equipment type code of the box, for example 45G1.

size_typestring | null

The line's own size and type label for the box.

statusstring | null

The box's own status, which can differ from the status of the document. One of: pre_departure, in_transit, at_transshipment, arriving, at_anchor, at_berth, discharged, customs_hold, available, delivered, returned_empty.

status_source"tracked" | "line" | "document" | null

Where the box status came from: its own tracked row, the line's events for that box, or the document status.

eventsarray

The box's own timeline; an empty array when no per-box timeline is known yet.

events[]object
event_codestring

Milestone code of the move, for example GTIN, LOAD, DEPA, ARRI, DISC or GTOT.

event_namestring

Readable name of the move, the same wording the dashboard shows.

event_family"EQUIPMENT" | "TRANSPORT" | "SHIPMENT"

Family the move belongs to.

transport_mode"VESSEL" | "RAIL" | "TRUCK" | "BARGE"

Conveyance the line stated for the move.

is_actualboolean

True when the move has happened, false when it is planned or estimated.

implied_actualtrue

True when a planned move is served as done because a later actual move proves it happened.

datetimestring

When the move happened or is planned, as a UTC instant when the port time zone is known.

datetime_localstring | null

The same moment on the port wall clock, without an offset.

timezonestring | null

IANA time zone of the port, for example Asia/Shanghai.

utc_offset_minutesinteger | null

Minutes to add to UTC to get the port wall clock.

time_semanticsstring

How the timestamp was obtained, so a client knows whether it is a true instant. One of: carrier_offset, tz_resolved, date_only, local_unplaced, legacy_unknown.

unlocodestring | null

UN/LOCODE of the place of the move.

location_code_sourcestring | null

Where the served UN/LOCODE came from. One of: carrier, matched_in_country, matched_port_name, corrected, not_determined, recorded.

port_namestring | null

Place name as the line wrote it.

facilitystring | null

Terminal, depot or other facility name as the line wrote it.

vessel_namestring | null

Name of the ship for this move.

vessel_imostring | null

IMO number of the ship for this move, as a string.

voyage_numberstring | null

Voyage number the line stated for this move.

descriptionstring | null

The line's own wording for the move.

carrier_status_textstring

The line's own status remark for the move.

empty_indicator"EMPTY" | "LADEN" | null

Whether the box was empty or laden at this move.

empty_indicator_source"carrier" | "not_reported"

Who stated the fill state: the line, or nobody.

gate_out_rolestring

What a gate-out did: moved the box on, or handed it to the consignee. One of: transfer, consignee_delivery, not_reported.

statusstring

Current normalised status of the shipment.

carrierstring

Carrier name, falling back to the SCAC when we hold no name.

vessel_namestring

Name of the carrying vessel, or null when the carrier named none.

vessel_imostring

IMO number of the carrying vessel, or null when unknown.

planned_vesselobject | null

The ship the box is waiting for: before its first actual load while its planned load at the port of loading is still ahead or at most 3 days past, or at a transshipment hub before the reload.

namestring | null

Name of the planned ship.

imostring | null

IMO number of the planned ship, as a string.

voyagestring | null

Voyage number of the planned sailing.

positionobject | null

Latest AIS position of the planned ship; null when the fix is older than 48 hours, the plan has lapsed, or the ship has already left the load port.

latnumber

Latitude of the ship.

lngnumber

Longitude of the ship.

updated_atstring

When the ship was observed at this position.

heading_toobject

The port where the box is planned to load.

unlocodestring | null

UN/LOCODE of the planned load port.

namestring | null

Name of the planned load port.

planned_load_atstring | null

When the box is planned to load onto this ship.

status"planned"

Always planned.

vessel_positionobject

Live AIS position of the carrying vessel.

latnumber

Latitude.

lngnumber

Longitude.

origin_namestring

Origin port name, falling back to its UN/LOCODE.

destination_namestring

Destination port name, falling back to its UN/LOCODE.

etastring

Arrival time (ISO 8601) of the vessel (the ARRI event) at the port in destination_unlocode: planned until it arrives, actual after (see eta_is_estimated).

eta_confidence_pctinteger

How often this lane arrives on time, as a percentage.

last_updated_atstring

The more recent of the carrier check and the AIS fix: when we last learned anything about this shipment.

last_updated_sourcestring

Which of the two produced last_updated_at: carrier_poll or ais_vessel_position.

last_polled_atstring

When we last asked the carrier (ISO 8601).

last_ais_fix_atstring

When the vessel was last actually observed by AIS, or null when we hold no fix.

field_provenanceRecord<string, object>

Per-field account of WHY a declared field is empty, keyed by field name.

{field}object
statestring

Why the field stands where it does: resolved, contract_required, not_published, not_applicable or awaiting_carrier.

actionstring

What would change the state: supply_terms, wait, or do_not_expect when nothing will.

sourcestring

Where the answer on this call came from: direct_carrier or warm_db.

confidencestring

On a card, whether the slot partners agree with each other.

evidencestring

The reasoning behind the state, in one sentence, so a support answer does not need our source.

demurrage_free_days_leftinteger | null

Days of free time left, or null when no terms are on file.

ai_narrativestring | null

Reserved for a written summary of the shipment.

eventsarray

Milestone timeline, oldest to newest.

events[]object
typestring

Event code, for example DEPA or LOAD.

classifierstring

DCSA classifier: ACT for actual, EST for estimated, PLN for planned.

is_actualboolean

True when the event happened.

labelstring

The event in plain words.

timestampstring

Event timestamp (ISO 8601).

event_local_datetimestring

The port wall-clock for the same moment, naive and with no offset, exactly as a terminal prints it.

utc_offset_minutesinteger

Minutes to add to the UTC instant to reach the local wall-clock.

event_timezonestring

IANA zone of the port, which survives a DST change in a way a bare offset cannot.

date_onlyboolean

True when the carrier published a calendar date with no time of day.

event_datestring | null

The calendar date, YYYY-MM-DD, when date_only is true.

locationstring

UN/LOCODE for the event, or null when the carrier gave no place.

empty_indicatorstring | null

EMPTY or LADEN, on equipment events.

empty_indicator_sourcestring

Who stated the fill state of an equipment event: carrier when the line reported EMPTY or LADEN, not_reported when it did not.

gate_out_rolestring

What a gate-out did, in the line's own words: transfer when the line says the box moved on (to another terminal, a rail ramp or a train), consignee_delivery when it says the consignee took the box, not_reported when it says neither.

equipment_referencestring

The container the event happened to.

vessel_namestring | null

Name of the ship for this move.

vessel_imostring | null

IMO number of the ship for this move, as a string.

voyagestring | null

Voyage number the line stated for this move.

line_date_suspecttrue

True on a past plan the line left behind a later actual move.

has_facilityboolean

True when the line named a terminal, hub or depot for this arrival.

carrier_document_replyobject | null

Latest retained, exact-reference OOCL document reply.

carrier_code"OOLU"
referencestring
reference_type"bl" | "booking"
status"cancelled" | "declined"
carrier_referencestring
carrier_noticeobject | null

Latest reference-specific reply from the named carrier.

carrier_code"ZIMU" | "MAEU" | "CHVW"
referencestring
reference_type"container" | "bl" | "booking"
statusstring

One of: other_carrier, temporarily_unavailable, not_found, invalid_reference, SHIPMENT_CANCELLED, no_longer_available.

messagestring
checked_atstring
suggested_carrierstring | null
suggested_urlstring | null
status_partialboolean | null

True when the boxes of a multi-box document are at different stages; null when it cannot be worked out.

discharge_partialboolean | null

True when some but not all boxes of a multi-box document have been discharged; null when it cannot be worked out.

predictive_etastring | null

Our own arrival forecast when it differs from the ETA served in eta; null when we have none, when it equals eta, or once the arrival is a fact.

ais_pol_departureobject | null

AIS saw the vessel carrying the box leave its port of loading while the line has not reported a departure there: the box's last actual load at that port names the vessel, nothing has discharged it there since, and the vessel's call at that port spans the load.

observed_atstring

When the ship left the port of loading, by our AIS port call record.

port_unlocodestring

UN/LOCODE of the port of loading.

port_namestring | null

Name of the port of loading.

timezonestring | null

IANA time zone of the port of loading.

vessel_imointeger

IMO number of the ship.

vessel_namestring | null

Name of the ship.

source"ais"

Always ais.

notestring

A sentence you can show as-is.

archived_atstring | null

When tracking stopped. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

archived_reasonstring | null

Null when your account archived it, otherwise the reason our archiver closed it. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

resumeobject

Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

methodstring
pathstring
bodyobject
identifierstring

The reference to add again.

errorobject

Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

codestring

Machine readable error code.

messagestring

Human readable explanation.

severity"info" | "warning" | "error"

How serious the error is.

retryableboolean

True.

referencestring

The reference.

retry_after_secondsinteger

Seconds to wait.

fieldsstring[]

Offending fields.

user_messagestring

CONTAINER_QUOTA_EXCEEDED only.

credits_requiredinteger | null

Tokens this request needs.

credits_balanceinteger | null

Tokens the wallet holds.

top_up_urlstring

Where to top up.

packagesarray

Plans on offer.

packages[]object
planstring

Plan key.

creditsinteger

Tokens per month.

usdnumber

Monthly price in USD.

reasonstring

CARRIER_NOT_IDENTIFIED only.

waited_secondsinteger

CARRIER_NOT_IDENTIFIED, timed out only.

retry_withstring
member_limitinteger | null

The member cycle limit.

member_spentinteger | null

Tokens the member has used this cycle.

member_remaininginteger | null

Tokens left for the member.

retry_afterinteger

Seconds until the next refresh is allowed.

request_idstring
requestedstring | null
supported_versionsstring[]
oldest_supportedstring
lateststring
docsstring
progressobject
carrier_codestring
carrier_namestring | null
carrier_identifiedtrue
registered_atstring | null
last_checked_atstring | null
next_check_after_seconds60
unresolved_reasonstring
outcomestring

One of: SEALINE_HASNT_PROVIDE_INFO, NO_EVENTS, WRONG_NUMBER, REFERENCE_REQUIRED, LINE_NOT_SUPPORTED, PENDING, UNRESOLVED.

outcome_classstring
sealine_statusstring | null
previous_tripobject | null

The trip before yours for this box, when the line still reports it.

linestring | null

The line that answered, as its SCAC.

last_eventobject
codestring | null
descriptionstring | null
locationstring | null
unlocodestring | null
datetimestring | null
eventsarray
events[]object
codestring | null
descriptionstring | null
locationstring | null
unlocodestring | null
datetimestring | null
ended_atstring | null
lessor_notestring | null

A note for leasing-company accounts when no line holds the box yet.

identified_linestring | null
identified_partystring | null
identified_party_role"current_lessee" | null
required_reference_types("bill_of_lading" | "booking")[] | null
connector_statusstring | null

One of: in_progress, not_supported, connected, reference_required.

notification_interest_availableboolean
carrier_noticeobject | null

Latest reference-specific reply from the named carrier. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

carrier_code"ZIMU" | "MAEU" | "CHVW"
referencestring
reference_type"container" | "bl" | "booking"
statusstring

One of: other_carrier, temporarily_unavailable, not_found, invalid_reference, SHIPMENT_CANCELLED, no_longer_available.

messagestring
checked_atstring
suggested_carrierstring | null
suggested_urlstring | null
carrier_hint_appliedboolean

Present when the line named was not used. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

carrier_hint_codestring

Known line that cannot be asked. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

upgradeobject | null

CONTAINER_QUOTA_EXCEEDED only. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

planstring

Next plan.

monthly_eurnumber | null

Monthly price.

annual_eurnumber | null

Annual price.

warningstring

Why the line named was not used. Only on status 202, 400, 401, 402, 403, 404, 409, 429, 500, 503 and 504.

Errors

A failure carries { "ok": false, "error": { "code", "message", "severity" } }. Branch on the code, and log the message.

TRACKING_IN_PROGRESS202

Not a failure and not a not-found. The identifier is registered and the carrier has not answered yet. The body carries retry_after_seconds. Poll again rather than adding the box a second time. Note that ok is false on a 202 here, so branch on the status, not on ok alone.

UNAUTHORIZED401

The key is missing, malformed or revoked.

INSUFFICIENT_CREDITS402

MCP calls on Navo Tokens only: your balance cannot pay for this call. Nothing is charged and no data is returned. Besides code and message, the error carries credits_required, credits_balance, top_up_url and packages (see Navo Tokens on the TrackingMCP reference page). A REST call on your API key never meets this.

REFERENCE_NOT_RESOLVABLE404

No line recognises this reference. Check the check digit before retrying: a wrong one keeps failing.

DB_ERROR500

We could not read the record. Retry.

curl 'https://api.navo24.com/v1/tracking/containers/lookup/MEDU1234562' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY"
Response
{
  "api_version": "2026-08-04",
  "ok": true,
  "data": {
    "id": "8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
    "container_number": "ONEU1234567",
    "bl_number": null,
    "identifier": "ONEU1234567",
    "identifier_type": "container_id",
    "booking_number": null,
    "container_size": "40HC",
    "equipment_type": "High Cube Dry",
    "iso_type_code": "45G1",
    "child_containers": null,
    "status": "discharged",
    "carrier": "Maersk",
    "vessel_name": "MAERSK NORDDAL",
    "vessel_imo": "9894674",
    "vessel_position": {
      "lat": 21.37788,
      "lng": 91.643204
    },
    "origin_name": "XIAMEN",
    "destination_name": "CHITTAGONG",
    "eta": "2026-08-14T07:24:00+00:00",
    "eta_confidence_pct": 97,
    "last_updated_at": "2026-08-16T11:20:18+00:00",
    "last_updated_source": "ais_position",
    "last_polled_at": "2026-08-16T03:50:21.692+00:00",
    "last_ais_fix_at": "2026-08-16T11:20:18+00:00",
    "field_provenance": {
      "last_updated_at": {
        "state": "resolved",
        "action": "none",
        "source": "ais_vessel_position",
        "confidence": "exact",
        "evidence": "The vessel carrying this shipment was observed at a position at 2026-08-16T11:20:18+00:00, more recently than our last carrier check at 2026-08-16T03:50:21.692+00:00. A position fix locates the ship; it does not report container milestones, so the carrier is still polled on its own cadence."
      }
    },
    "demurrage_free_days_left": null,
    "ai_narrative": null,
    "events": [
      {
        "type": "GTOT",
        "classifier": "ACT",
        "is_actual": true,
        "label": "Gate out",
        "timestamp": "2026-07-25T04:05:00+00:00",
        "event_local_datetime": "2026-07-25T12:05:00",
        "utc_offset_minutes": 480,
        "event_timezone": "Asia/Shanghai",
        "date_only": false,
        "event_date": null,
        "location": "CNXMN"
      },
      {
        "type": "GTIN",
        "classifier": "ACT",
        "is_actual": true,
        "label": "Gate in",
        "timestamp": "2026-07-25T11:05:00+00:00",
        "event_local_datetime": "2026-07-25T19:05:00",
        "utc_offset_minutes": 480,
        "event_timezone": "Asia/Shanghai",
        "date_only": false,
        "event_date": null,
        "location": "CNXMN"
      }
    ]
  }
}