> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primefreight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a tracking request

> Start tracking a shipment by container number or bill of lading.

Tracking starts with a request. Send a carrier SCAC together with a container number or a master bill of lading, and PrimeFreight begins tracking the shipment. When the data resolves it becomes available as a [shipment](/api-reference/v2/get-shipment) and [container](/api-reference/v2/get-container) you can retrieve, and any [webhooks](/api-reference/v2/webhooks) you've registered begin firing.

`POST /v2/tracking_requests`

## Request body

Send the carrier `scac` plus at least one identifier — `bill_of_lading` or `container_number`.

<ParamField body="scac" type="string" required>
  Carrier SCAC code — e.g. `MAEU`.
</ParamField>

<ParamField body="bill_of_lading" type="string">
  Master bill of lading number. Provide this or `container_number`.
</ParamField>

<ParamField body="container_number" type="string">
  Container number — e.g. `ABCU1234567`. Provide this or `bill_of_lading`.
</ParamField>

<ParamField body="reference" type="string">
  Your own reference, echoed back on the resulting shipment.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.primefreight.com/v2/tracking_requests \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "scac": "MAEU",
      "bill_of_lading": "DUMYMBL0001"
    }'
  ```
</RequestExample>

## Response

Returns the created tracking request. `status` is `pending` until the carrier returns data — follow its progress with [webhooks](/api-reference/v2/webhooks) or the status check below. When it succeeds, `shipment_id` links to the shipment.

| Field              | Type   | Description                                                     |
| ------------------ | ------ | --------------------------------------------------------------- |
| `id`               | string | Tracking request ID                                             |
| `status`           | string | `pending`, `succeeded`, or `failed`                             |
| `scac`             | string | Carrier SCAC submitted                                          |
| `bill_of_lading`   | string | Bill of lading submitted, or `null`                             |
| `container_number` | string | Container number submitted, or `null`                           |
| `reference`        | string | Your reference, or `null`                                       |
| `shipment_id`      | string | The resulting shipment once tracking resolves, otherwise `null` |
| `created_at`       | string | When the request was created                                    |

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "trq_100001",
    "status": "pending",
    "scac": "MAEU",
    "bill_of_lading": "DUMYMBL0001",
    "container_number": null,
    "reference": null,
    "shipment_id": null,
    "created_at": "2026-07-17T09:00:00-04:00"
  }
  ```
</ResponseExample>

## Check a request's status

Retrieve a request at any time to see whether tracking has resolved. `status` becomes `succeeded` (with a `shipment_id`) or `failed`.

`GET /v2/tracking_requests/{id}`

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.primefreight.com/v2/tracking_requests/trq_100001 \
    -H "Authorization: Bearer <token>"
  ```
</RequestExample>