---
title: "Start tracking a container, bill of lading, or booking"
method: POST
path: "/v1/containers"
---

# Start tracking a container, bill of lading, or booking

`POST /v1/containers`

## Request

- Base URL: `https://api.trackingmcp.com`
- URL: `https://api.trackingmcp.com/v1/containers`
- Auth: HTTP bearer

## Request body

- object
  - `identifier` string, required
  - `identifier_type` 'container_id' | 'bill_of_lading' | 'booking', required
  - `carrier_code` string: Optional SCAC hint; auto-resolved from the container prefix when omitted.
  - `tags` string[]
  - `tracked_from` string, date-time: Journey floor for a re-used container number (ISO 8601 date or date-time). Events dated before it are dropped from derivation and the timeline, so a container reused on a new booking scopes to the current sailing instead of a delivered prior journey. Applies to container-number registrations; bill_of_lading and booking references already pin the journey and ignore it.
  - `bl_number` string: Bill of lading number sent with a container identifier. Required when carrier_code names a line that tracks only by the bill of lading and the container number together (JJCU, Shanghai Jinjiang); ignored for every other line.
  - `container_number` string: Container number (4 letters and 7 digits) sent with a bill_of_lading or booking identifier. Required when carrier_code names a line that tracks only by the bill of lading and the container number together (JJCU, Shanghai Jinjiang); ignored for every other line.

## Response `200`

Container accepted and tracking started.

- object
  - `ok` true, required
  - `api_version` string: The response contract this build answers, as a date. Pin it in your client.
  - `data` CreatedContainer, required: The payload. Everything an endpoint returns sits under this key.
    - `id` string: 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.
    - `identifier` string: The container number, bill of lading or booking this record tracks.
    - `status` string: 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.
    - `carrier_code` string: Carrier SCAC.

## Other responses

- `400`: Validation error.
- `401`: Missing or invalid API key.
- `404`: The shipping line could not be identified automatically (no line from carrier_code, the container prefix or the document shape, and none found within about 70 seconds). Repeat the request with the line SCAC in carrier_code. Only API-key requests that do not name a line wait for this answer; the reference stays registered and the search continues, so a repeat add with carrier_code records the line on the same shipment.
- `409`: Already in your tracking list.

---

[API](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api.md) · [All operations](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api/revisions/6bb8d8172ceb?raw)