Create a tracking request

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 and container you can retrieve, and any 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.

string

required

Carrier SCAC code — e.g. MAEU.

string

Master bill of lading number. Provide this or container_number.

string

Container number — e.g. ABCU1234567. Provide this or bill_of_lading.

string

Your own reference, echoed back on the resulting shipment.

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"
  }'

Response

Returns the created tracking request. status is pending until the carrier returns data — follow its progress with 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

{
  "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"
}

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}

curl https://api.primefreight.com/v2/tracking_requests/trq_100001 \
  -H "Authorization: Bearer <token>"

​Request body

​Response

​Check a request’s status

Request body

Response

Check a request’s status