# OpenTrack API Documentation ## Guides - [Getting Started](https://developers.opentrack.co/docs/getting-started.md) - [OpenTrack Overview](https://developers.opentrack.co/docs/opentrack-overview.md) - [Tracking Requirements](https://developers.opentrack.co/docs/tracking-requirements.md) - [Carrier + Terminal Coverage](https://developers.opentrack.co/docs/carrier-terminal-coverage.md) - [Rail Visibility](https://developers.opentrack.co/docs/rail-tracking.md) - [Rate Limits](https://developers.opentrack.co/docs/rate-limits.md) - [Export Visibility](https://developers.opentrack.co/docs/n-american-export-visibility.md) - [Map Routes API](https://developers.opentrack.co/docs/map-routes-api.md) - [Data Source Attribution via API](https://developers.opentrack.co/docs/milestone-and-eta-attribution-via-api.md): OpenTrack's API provides detailed insight into the origin of key data points like ETAs and milestones. This guide explains how to access and interpret that attribution data. - [Container Milestones](https://developers.opentrack.co/docs/container-voyage-milestones.md) - [Past and Future Milestones in the API](https://developers.opentrack.co/docs/past-future-milestones-in-the-api.md): This guide explains how to retrieve both historical and upcoming milestones—including ETDs, ETAs, and transshipment events—using OpenTrack’s API. - [Holds & Demurrage](https://developers.opentrack.co/docs/demurrage-last-free-day.md): How are holds & demurrage reported? - [AIS Vessel Tracking](https://developers.opentrack.co/docs/ais-vessel-tracking.md) - [Vessels & Voyages](https://developers.opentrack.co/docs/vessels-voyages.md) - [Last Free Day (LFD) via API](https://developers.opentrack.co/docs/how-to-use-opentracks-last-free-day-lfd-via-api.md) - [Tracking Best Practices](https://developers.opentrack.co/docs/tracking-lifecycle.md) - [Tracking Failed Events](https://developers.opentrack.co/docs/tracking-failed-events.md) - [Tracking Stopped Events](https://developers.opentrack.co/docs/tracking-stopped-events.md) ## API Reference - [Track a Container](https://developers.opentrack.co/reference/trackcontainer.md): The container tracking request endpoint allows you to import a container to be tracked by OpenTrack. Once a container has been imported for tracking, you will be able to retrieve all available container status and milestone data. In order to successfully provide tracking, please provide the Master Bill of Lading number issued by the carrier and SCAC code. See All Supported Carriers for a list of supported carriers. #### Webhooks If you prefer to receive webhook notifications for key events related to this container, please see the Webhooks Section. #### Important Note By default OpenTrack will track all the containers on any Master Bill of Lading you send us, even if you use the /conainers endpoint. Most view this as a helpful feature that saves redundant requests. OpenTrack does have a setting that lets you restrict tracking to just the single container you send, and we won't track the rest of the containers on the master bill. Let us know if you want this setting activated by emailing support@opentrack.co. - [Get Container Status](https://developers.opentrack.co/reference/getcontainerstatus.md): The container status and milestone request endpoint provides the abundance of tracked container data generated by OpenTrack. Once a container has been imported for tracking either through the OpenTrack dashboard or via the POST Container Tracking Request endpoint, you will be able to retrieve all available container status and milestone data. ### Current Limitations #### Event Locations We are constantly evolving our locations database for precision and standardization. If you're expecting UN/LOCODEs to reconcile locations with your system, you'll find them reliably present in the `originPort` & `destinationPort` objects. The history events will have them when the location is of type `port`. For the moment, locations of a different type will not reliably contain the UN/LOCODE. - [OpenTrack Carrier + Terminal Coverage](https://developers.opentrack.co/reference/supported-carriers-1.md) - [Get Container Route](https://developers.opentrack.co/reference/getcontainerroute.md): Retrieve the complete route and journey segments for a tracked container, including origin-to-destination path with all intermediate points. The response includes: - Current container location and status - Journey segments (origin, ocean, destination) - Transportation modes for each segment - Actual vs estimated route classifications - GeoJSON formatted location points and route paths Each route segment contains from/to location points and the transportation path between them, allowing you to visualize the complete container journey on a map. - [Register a Webhook](https://developers.opentrack.co/reference/registerwebhook.md): OpenTrack offers the ability for developers to subscribe to various events that occur in the container lifecycle. When these events occur, we will ping the server defined at the configured webhook URL with data relevant to the event. In this request, pass in your desired Webhook URL and the events you would like to consume. If no events are provided, the webhook will include all event types. See All Webhook Event Types for the list of possible event types to consume. The API will enforce unique webhook URLs in your account. It will return a `VALIDATION_ERROR` if an attempt is made to register a webhook with a URL that is already registered. ### Using A Secret For Added Security Optionally, you can specify a `secret` in the registration request, which we will use to identify webhook requests from OpenTrack. (See Validating Webhooks) ### Receiving Webhooks When these events occur, we will send a `POST` request to your webhook URL. You can expect these events to have a latency of up to 1 minute of the actual event taking place. If our `POST` request to your endpoint fails (meaning we receive a 4xx or 5xx status code in response), then we will retry the same `POST` request, no more than 30 minutes later, and keep repeating every 30 minutes until: - We receive a 2xx response from your server. - We have attempted to reach your server with this webhook event 5 times. The webhook payload will look like the following: ```json { "data": {...}, "changes": { "status": { "previous": "DISCHARGED", "current": "AVAILABLE" } }, "deliveryAttempt": 1, "pendingRetries": 4, "event": "container.status.updated", "sentAt": "2019-07-19T17:00:00.654Z" } ``` The contents of data vary depending on the webhook event type. Take a look at the Webhooks section of the docs for more details. ### Validating Webhooks In the webhook event request, we will also send a `X-OpenTrack-Signature` header which can be used to verify that this webhook event is indeed coming from OpenTrack. To validate, encrypt the incoming webhook payload with your webhook config secret key. Check that this generated signature matches the signature in X-OpenTrack-Signature header. For example, in Javascript: ```javascript const crypto = require("crypto"); const hmac = crypto.createHmac("sha256", secret); const signature = hmac.update(JSON.stringify(webhookPayload)).digest("hex"); ``` - [List Webhooks](https://developers.opentrack.co/reference/listwebhooks.md): This endpoint allows you to list the webhooks registered to your account. - [Update a Webhook](https://developers.opentrack.co/reference/updatewebhook.md): Change the name, secret, and events list for an existing webhook. Calling this endpoint is equivalent to unregistering a webhook and registering it again with different options. For a list of event types that can be consumed, see the endpoint to register a webhook. The list of event types specified in the request body is considered exhaustive. Event types consumed by the webhook previously are overwritten when it is updated. Leave the `events` parameter out of the request body to maintain the list of event types as is. If the parameter is included as an empty list, the webhook will be updated to include all event types. - [Unregister a Webhook](https://developers.opentrack.co/reference/deletewebhooks.md): This endpoint allows you to unregister a webhook in your account. - [All Webhook Event Types](https://developers.opentrack.co/reference/all-webhook-event-types-1.md): Full list of events that your application can be notified of by subscribing to webhooks. - [Track a Master Bill](https://developers.opentrack.co/reference/trackmasterbill.md): The master bill tracking request endpoint allows you to import a master bill to be tracked by OpenTrack. Once a master bill has been imported for tracking, we will gather all of the containers associated with it, and you will be able to retrieve all available container status and milestone data via webhooks (if subscribed) or via the GET /containers endpoint. In order to successfully provide tracking, please provide the Master Bill of Lading number issued by the carrier and SCAC code. See All Supported Carriers for a list of supported carriers. - [Get Master Bill Status](https://developers.opentrack.co/reference/getmasterbillstatus.md): Receive a status update for all containers on a master bill using just the master bill number. - [Get Webhook Events](https://developers.opentrack.co/reference/getevents.md): This endpoint allows you to playback all the webhook event messages sent to your account endpoint(s). The response looks as follows: ```json { total: 1 data: [{ "event": "container.status.updated" "sentAt": "2025-05-27T07:42:32.950Z" "data": {...}, "changes": { "status": { "previous": "DISCHARGED", "current": "AVAILABLE" } }, }] } ```