Navo24 / TrackingMCP

Migrate from Navo24 / TrackingMCP to TimeToCargo API v2: authentication, requests and response handling

This guide covers migration from Navo24 REST API v1 to TimeToCargo API v2. Navo24 POST /v1/containers immediately returns a permanent record ID. A TimeToCargo batch request first returns a temporary task ID. Retrieve the permanent tracking ID from the task result.

See the migration workflow for importing references and setting up notifications. Full TimeToCargo schemas are in the API reference.

Authentication

Navo24 uses the Authorization: Bearer tmcp_… header. The Navo24 / TrackingMCP base URL is https://api.trackingmcp.com.

To switch to TimeToCargo:

Create a key in your TimeToCargo account.
Change the base URL to https://tracking.timetocargo.com/v2. For example, the full tracking endpoint is https://tracking.timetocargo.com/v2/tracking.
Send the new key in the api_key query parameter of every request, including batch tasks and webhook management. Keys and tokens from the former provider cannot be reused.

See authentication for key usage and request limits.

Tracking records and identifiers

Navo24 / TrackingMCP	TimeToCargo	Required change
`container record (data.id)`	`shipment.id`	Map the source `data.id` to the new tracking ID. A bill of lading or booking result can contain several containers.
`identifier`	`track_number`	Pass `identifier` as the tracking reference. Do not replace it with the internal Navo24 record ID.
`container status`	`shipment_status`	Read shipment progress from `shipment_status`. Check the subscription status, `ACTIVE` or `ARCHIVED`, separately.

Operation mapping

Navo24 / TrackingMCP	TimeToCargo	Required change
`POST /v1/containers`	`POST /v2/tracking/batch` → `GET /v2/tracking/batch`	Submit references, save `task_id`, and retrieve the task results. Then save each reference's permanent `data.results[].data.tracking_metadata.id`.
`GET /v1/containers`	`GET /v2/shipments`	Replace `cursor` with `page` and `limit`. Use `status=ACTIVE` for active subscriptions.
`GET /v1/containers/{id}, GET /v1/containers/lookup/{identifier}`	`GET /v2/shipments`	Fetch `/v2/shipments` pages and find the record by its saved new `id`. There is no individual lookup by ID or reference.
`POST /v1/containers/{id}/recheck`	`GET /v2/tracking?force_update=true`	Pass the reference, type and SCAC together with `force_update=true`. This request does not use the Navo24 record ID.
`DELETE /v1/containers/{id}`	`DELETE /v2/shipments`	Send the new IDs in the `shipmentIds` body array. Check archiving and deletion rules in the lifecycle guide.
`/v1/webhooks: POST/GET/PATCH/DELETE/test`	`/v2/webhooks`	Create new webhooks and configure the secret, signature verification and notification parsing using the webhook guide.
`GET /v2/events, summary, demurrage`	No direct equivalent	Read events from `containers[].events[]`. Separately retain DCSA data and demurrage calculations used by your system.

Request parameters

Navo24 / TrackingMCP	TimeToCargo	Required change
`identifier`	`tracked_items[].track_number.value`	In the `POST /v2/tracking/batch` body, copy `identifier` into `tracked_items[].track_number.value`.
`identifier_type`	`tracked_items[].track_number.type`	Replace `container_id` with `container`, `bill_of_lading` with `bl`, and `booking` with `bk`.
`carrier_code`	`tracked_items[].company`	Find the carrier through `GET /v2/companies` and pass its `scac` in `tracked_items[].company`.
`cursor / limit / archived`	`page / limit / status`	Switch to numbered pages using `page`. Use `status=ARCHIVED` for archived records and `status=ACTIVE` for active ones.
`bl_number / container_number`	No complete equivalent	Choose one primary reference. If Navo24 requires both a bill of lading and a container for a carrier, test tracking with the chosen reference separately.
`tags / tracked_from`	`note` / no equivalent	Save one label of up to 40 characters as `note` through `PATCH /v2/shipments/{id}`. Keep other tags locally. There is no `tracked_from` event cutoff.

Response fields

Select a record from data.data[] in the GET /v2/shipments response. Paths starting with tracked_item are relative to that record. Containers are in tracked_item.data.data.containers[], with events in each container's events[]. In GET /v2/tracking, shipment data is directly under data.

Navo24 / TrackingMCP	TimeToCargo	Response handling
`data.items[]`	`data.data[]`	Iterate over `data.data` instead of `data.items`. Continue fetching pages through `data.meta.totalPages`.
`data.items[].id`	`data.data[].id`	Store new IDs alongside the source Navo24 IDs. Use only the new IDs to edit labels or stop tracking.
`identifier / identifier_type`	`tracked_item.track_number / tracked_item.track_number_type`	In the selected record, read the reference from `tracked_item.track_number` and its type from `tracked_item.track_number_type`.
`status`	`tracked_item.data.data.shipment_status`	Replace Navo24 status handling with `shipment_status` values, for example `in_transit` with `IN_TRANSIT`. The record's outer `status` describes the subscription.
`events / route / current position`	`tracked_item.data.data.containers[].events / route_info`	Read events from the selected record's `tracked_item.data.data.containers[].events[]`. Add `need_route=true` to the list request when you need `route_info`.

Response examples

Each pair labels the former-provider and TimeToCargo responses. Expand the longer JSON examples when you need them; the mapping tables remain visible. These are shortened examples with illustrative data. The path above each JSON block identifies the part shown. Paths in the following table start from that part.

Request acceptance and two ID types

Navo24 / TrackingMCP — POST /v1/containers

Shortened response.

{
    "ok": true,
    "data": {
        "id": "33333333-3333-4333-8333-333333333333",
        "identifier": "MSCU1234567",
        "status": "unknown",
        "carrier_code": "MSCU"
    }
}

TimeToCargo — POST /v2/tracking/batch

Shortened response.

{
    "success": true,
    "status": "OK",
    "data": {
        "task_id": "22222222-2222-4222-8222-222222222222"
    }
}

How to map

Navo24 / TrackingMCP	TimeToCargo	Required change
`data.id = "33333333-3333-4333-8333-333333333333"`	`data.task_id = "22222222-2222-4222-8222-222222222222"`	Do not save `task_id` as the tracking ID. Retrieve the task result and take the permanent ID from `data.results[].data.tracking_metadata.id`.
`data.identifier = "MSCU1234567"`	No direct equivalent	Keep the submitted reference locally until results arrive. The task-creation response contains only the task ID.
`data.status = "unknown"`	`status = "OK"`	`OK` confirms that the request was accepted. Shipment progress will be available in the task result's `shipment_status`.

The creation response contains only the task ID. After PROCESSED, retrieve the permanent ID from data.results[].data.tracking_metadata.id. Use it to locate the stored record and update its label.

List, reference type and ETA

Navo24 / TrackingMCP — GET /v1/containers

Shortened response.

{
    "ok": true,
    "data": {
        "items": [
            {
                "id": "33333333-3333-4333-8333-333333333333",
                "identifier": "MSCU1234567",
                "identifier_type": "container_id",
                "carrier_code": "MSCU",
                "carrier_name": "MSC",
                "status": "in_transit",
                "eta": "2026-10-12T08:00:00+02:00",
                "eta_is_estimated": true,
                "destination_name": "Rotterdam",
                "tags": ["Order 123"],
                "archived_at": null
            }
        ],
        "has_more": false
    }
}

TimeToCargo — GET /v2/shipments

Shortened response.

{
    "success": true,
    "status": "OK",
    "data": {
        "data": [
            {
                "id": "11111111-1111-4111-8111-111111111111",
                "status": "ACTIVE",
                "note": "Order 123",
                "track_number": "MSCU1234567",
                "tracked_item": {
                    "track_number": "MSCU1234567",
                    "track_number_type": "container",
                    "data": {
                        "success": true,
                        "status": "OK",
                        "data": {
                            "summary": {
                                "company": {
                                    "name": "MSC",
                                    "scacs": ["MEDU", "MSCU"]
                                },
                                "pod": {
                                    "location": 1,
                                    "date": "2026-10-12T08:00:00"
                                }
                            },
                            "shipment_status": "IN_TRANSIT",
                            "locations": [
                                {
                                    "id": 1,
                                    "name": "Rotterdam",
                                    "country": "Netherlands",
                                    "lat": 51.95,
                                    "lng": 4.14
                                }
                            ],
                            "containers": [
                                {
                                    "number": "MSCU1234567",
                                    "events": [
                                        {
                                            "location": 1,
                                            "status": "Vessel arrival",
                                            "status_code": "VAD",
                                            "date": "2026-10-12T08:00:00",
                                            "actual": false,
                                            "vessel": "EXAMPLE VESSEL",
                                            "voyage": "126E"
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                }
            }
        ],
        "meta": {
            "currentPage": 1,
            "totalPages": 1,
            "totalItems": 1
        }
    }
}

How to map

Navo24 / TrackingMCP	TimeToCargo	Required change
`data.items[0].id = "33333333-3333-4333-8333-333333333333"`	`data.data[0].id = "11111111-1111-4111-8111-111111111111"`	Map the Navo24 ID to the new `id`. Container numbers remain unchanged.
`data.items[0].identifier_type = "container_id"`	`data.data[0].tracked_item.track_number_type = "container"`	Read the type from `tracked_item.track_number_type`. For a container, the value is `container`.
`data.items[0].status = "in_transit"`	`data.data[0].tracked_item.data.data.shipment_status = "IN_TRANSIT"`	Read progress from `tracked_item.data.data.shipment_status`. The example value is `IN_TRANSIT`.
`data.items[0].eta = "2026-10-12T08:00:00+02:00"`	`data.data[0].tracked_item.data.data.summary.pod.date = "2026-10-12T08:00:00"`	Use `summary.pod.date` for arrival at the discharge port. Do not substitute it for final delivery to the destination address.
`data.items[0].eta_is_estimated = true`	`data.data[0].tracked_item.data.data.containers[0].events[0].actual = false`	Check `actual=false` for an event with an estimated date. `eta_is_estimated=true` does not mean arrival has occurred.
`data.items[0].tags = ["Order 123"]`	`data.data[0].note = "Order 123"`	Move one required tag into `note` if it fits within 40 characters. Keep the remaining tags in your system.
`data.has_more = false`	`data.meta.totalPages = 1`	Instead of `has_more`, compare the current page with `data.meta.totalPages` and increment `page`.

Dates illustrate field formats. Preserve source offset and timezone meaning: deleting Z or +08:00 is not a timezone conversion.

Event and position from the detail response

Navo24 / TrackingMCP — GET /v1/containers/{id}

Fragment: data.

{
    "container_number": "MSCU1234567",
    "events": [
        {
            "event_type": "EQUIPMENT",
            "equipment_event_type_code": "LOAD",
            "event_classifier_code": "ACT",
            "event_date_time": "2026-10-01T12:00:00+08:00",
            "equipment_reference": "MSCU1234567",
            "transport_call": {
                "location": {
                    "locationName": "Singapore",
                    "UNLocationCode": "SGSIN"
                }
            }
        }
    ],
    "vessel_position": {
        "name": "EXAMPLE VESSEL",
        "lat": 1.25,
        "lng": 103.75,
        "position_fix_at": "2026-10-03T08:30:00Z"
    },
    "eta_confidence_pct": 85
}

TimeToCargo — GET /v2/shipments?need_route=true

Fragment: data.data[0].tracked_item.data.data.

{
    "locations": [
        {
            "id": 0,
            "name": "Singapore",
            "country": "Singapore",
            "lat": 1.25,
            "lng": 103.75
        }
    ],
    "containers": [
        {
            "number": "MSCU1234567",
            "events": [
                {
                    "location": 0,
                    "status": "Loaded",
                    "status_code": "CLL",
                    "date": "2026-10-01T12:00:00",
                    "actual": true,
                    "vessel": "EXAMPLE VESSEL",
                    "voyage": "126E"
                }
            ]
        }
    ],
    "route_info": {
        "current_position": [1.25, 103.75],
        "last_updated": "2026-10-03T09:00:00"
    }
}

How to map

Navo24 / TrackingMCP	TimeToCargo	Required change
`events[0].equipment_reference = "MSCU1234567"`	`containers[0].number = "MSCU1234567"`	Find the container by `containers[].number` and process its `events`.
`events[0].equipment_event_type_code = "LOAD"`	`containers[0].events[0].status_code = "CLL"`	Here, `LOAD` is at the origin port and corresponds to `CLL`. Check a separate code for loading at other journey stages.
`events[0].event_classifier_code = "ACT"`	`containers[0].events[0].actual = true`	Replace `ACT` with `actual=true`, and `EST` and `PLN` with `actual=false`.
`events[0].transport_call.location`	`locations[0]`	Resolve `event.location` through `locations`. Use the source name and UN/LOCODE when checking the location match.
`vessel_position`	`route_info.current_position = [1.25,103.75]`	Read the current point from `route_info.current_position` as `[latitude, longitude]`. Route `last_updated` does not replace the AIS measurement time.
`eta_confidence_pct = 85`	No direct equivalent	There is no forecast confidence percentage field. Do not derive it from the planned date or shipment status.

Data to retain separately

After batch submission, retrieve the task result with status PROCESSED and save permanent IDs from data.results[].data.tracking_metadata.id. These examples cover the Navo24 REST API. SeaRates compatibility mode and DCSA use different formats, so review those handlers separately.

Navo24 / TrackingMCP

AuthenticationCopy Anchor Link

Tracking records and identifiersCopy Anchor Link

Operation mappingCopy Anchor Link

Request parametersCopy Anchor Link

Response fieldsCopy Anchor Link

Response examplesCopy Anchor Link

Request acceptance and two ID typesCopy Anchor Link

List, reference type and ETACopy Anchor Link

JSON examples

Event and position from the detail responseCopy Anchor Link

JSON examples

Data to retain separatelyCopy Anchor Link

Authentication

Tracking records and identifiers

Operation mapping

Request parameters

Response fields

Response examples

Request acceptance and two ID types

List, reference type and ETA

Event and position from the detail response

Data to retain separately