Introduction
The Tracking API lets you subscribe to a shipment (by container number, booking number, or bill of lading) and receive DCSA-standard tracking events as the shipment moves through the carrier's network, without integrating with each carrier yourself.
The flow
Integrating is four steps, and only the webhook one is optional:
- Authenticate: every request needs your API key in the
x-api-keyheader. See Authentication. - Set up carrier credentials: your account needs working credentials for each carrier you'll track. See Carrier Credentials.
- Set up a webhook (optional): if you want events pushed to your own endpoint as they happen, configure and activate a webhook first. If you'd rather pull data on your own schedule, skip this step entirely. See Webhooks.
- Subscribe: tell the service which shipments to track, by container number, booking number, or bill of lading. See Subscriptions.
Getting data back
Once subscribed, there are two ways to receive tracking data; which one applies depends on whether you set up a webhook in step 3:
| How it works | |
|---|---|
| Webhook (event-driven) | New events are POSTed to your endpoint as they arrive, wrapped with the subscription's references. Nothing to poll. |
| Pull (on demand) | Call GET /subscription/equipment with the booking number or bill of lading (or look a subscription up by its reference) whenever you want the latest state. |
Both return the same DCSA-standard events, so you can start with pulling and add a webhook later without changing how you parse the data.
POST /events is a different use case from everything above: it's how a
carrier whose integration is event-driven, or who isn't on our supported
list yet, pushes DCSA-standard events into the platform. As an API consumer you
never call it. See the Events guide.
Where to find it
| API | api.tracking.cif-consulting.co.uk |
You can download the OpenAPI schema to import into Postman or a client generator.