POSTAPI key

Start tracking

POSTapi.trackingmcp.com/v1/containers

Add a container, bill of lading or booking to your account. We resolve the carrier, backfill history and keep it live. Both identifier and identifier_type are required; a body without them answers 400 VALIDATION_ERROR.

Request body

identifierstringrequired

The reference to track: a container number, a bill of lading, or a booking. 1 to 50 characters.

identifier_typestringrequired

What the identifier is. One of container_id, bill_of_lading, booking. Note the keyed surface says booking where the public tracker says booking_number.

carrier_codestring

Optional SCAC hint, 2 to 10 characters. Omit it and we resolve the line from the container prefix.

tagsstring[]

Optional labels of your own, up to 20. They come back on the list endpoint and can filter it.

Response fields

Derived from the example response.

okboolean

Whether the request succeeded.

dataobject

The payload. Everything an endpoint returns sits under this key.

data.idstring

Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number.

data.identifierstring

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

data.statusstring

Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered.

data.carrier_codestring

Carrier SCAC.

data.sourcestring

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

Errors

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

VALIDATION_ERROR400

The body is not JSON, or identifier or identifier_type is missing or out of range. This is what you get for posting the wrong field names.

UNAUTHORIZED401

The key is missing, malformed or revoked.

UNIQUE_QUOTA_EXCEEDED402

The add would take you past the shipment quota on your plan.

CONTAINER_QUOTA_EXCEEDED402

No container slot is free on your plan. The body names the plan you would need.

PAYG_SPEND_CAP_REACHED402

Pay-as-you-go only: the add would cross the spend cap you set.

ALREADY_TRACKED409

You are already tracking this identifier. Read the existing record instead of adding it twice.

CONTAINER_ADD_IN_PROGRESS409

The same identifier is mid-add on another request. Wait and read it back.

INTERNAL_ERROR500

We failed to open the record. Nothing was charged against your quota.

curl -X POST 'https://api.trackingmcp.com/v1/containers' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"MEDU1234562","identifier_type":"container_id"}'

const res = await fetch("https://api.trackingmcp.com/v1/containers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tmcp_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "identifier": "MEDU1234562",
    "identifier_type": "container_id"
  })
});
const data = await res.json();

import requests

res = requests.post(
    "https://api.trackingmcp.com/v1/containers",
    headers={"Authorization": "Bearer tmcp_YOUR_API_KEY"},
    json={
      "identifier": "MEDU1234562",
      "identifier_type": "container_id"
    },
)
data = res.json()

Response

{
  "ok": true,
  "data": {
    "id": "8f1c2d4e-6a3b-4f52-9c70-11ab22cd33ef",
    "identifier": "MEDU1234562",
    "status": "in_transit",
    "carrier_code": "MSCU",
    "source": "direct_carrier"
  }
}