--- title: "Create a tracking request" method: POST path: "/tracking_requests" tags: ["Tracking Requests"] --- # Create a tracking request `POST /tracking_requests` To track an ocean shipment, create a new tracking request. `request_type` and `request_number` are always required. Supply either a shipping line `scac` or set `auto_detect_vocc_scac` to `true` to have Terminal49 infer the SCAC from the request number before creating the tracking request. Auto-detection uses the same carrier prediction capability as the Infer Tracking Number endpoint and runs asynchronously. The tracking request is created immediately (HTTP `201`) with `status: "pending"`; if no supported carrier can be inferred it transitions to `status: "failed"` with `failed_reason: "scac_auto_detect_failed"` and no shipment is created. Once a tracking request is created we will attempt to fetch the shipment details and its related containers from the shipping line. If the attempt is successful we will create a new shipment object including any related container objects. We will send a `tracking_request.succeeded` webhook notification to your webhooks. If the attempt to fetch fails then we will send a `tracking_request.failed` webhook notification to your `webhooks`. A `tracking_request.succeeded` or `tracking_request.failed` webhook notification will only be sent if you have at least one active webhook.

This endpoint is limited to 100 tracking requests per minute. ## Request body - object - `data` object - `attributes` object - `request_type` 'bill_of_lading' | 'booking_number' | 'container', required — The type of document number to be supplied. Container number support is currently in BETA. - `request_number` string, required - `scac` string — The carrier SCAC to use for this tracking request. Required unless `auto_detect_vocc_scac` is `true`. - `auto_detect_vocc_scac` boolean — Set to `true` to have Terminal49 infer the carrier SCAC from `request_number` when `scac` is not supplied. Detection is asynchronous: the tracking request is created immediately (HTTP `201`) with `status: "pending"` and `scac: null`. If a carrier is inferred, the request transitions to `status: "created"` with the detected `scac` populated. If no supported carrier can be inferred, it transitions to `status: "failed"` with `failed_reason: "scac_auto_detect_failed"` and no shipment is created. Poll the tracking request or use webhooks to observe the outcome — the create response does not include the detected `scac`. - `ref_numbers` string[] — Optional list of reference numbers to be added to the shipment when tracking request completes - `shipment_tags` string[] — Optional list of tags to be added to the shipment when tracking request completes - `initial_custom_fields` object — Optional custom field values to stage before the shipment and containers exist. Terminal49 applies `shipment` entries to the shipment and `containers` entries to matching containers once the tracking request resolves. Each `api_slug` must reference an existing custom field definition on your account. - `shipment` object[] — Custom field values to apply to the shipment created by this tracking request. - `api_slug` string, required — The `api_slug` of a custom field definition scoped to the `Shipment` entity type. - `value` union, required — Raw custom field value (type depends on definition) - string - number - boolean - string[] - object - `containers` object[] — Custom field values to apply to the containers created by this tracking request. Include `number` to target one specific container; omit it (or pass an empty string) to apply the value to every container on the shipment. - `api_slug` string, required — The `api_slug` of a custom field definition scoped to the `Container` entity type. - `value` union, required — Raw custom field value (type depends on definition) - string - number - boolean - string[] - object - `number` string — Container number to target. Omit this field, or pass an empty string, to broadcast this value to every container on the shipment. - `relationships` object - `customer` object - `data` object - `id` string, uuid - `type` 'party' - `type` 'tracking_request', required ## Response `201` Tracking Request Created - object - `data` TrackingRequest - `id` string, uuid, required - `type` 'tracking_request', required - `attributes` object - `request_number` string, required - `ref_numbers` string[], nullable - `tags` string[] - `status` 'pending' | 'awaiting_manifest' | 'created' | 'failed' | 'tracking_stopped', required - `failed_reason` 'booking_cancelled' | 'duplicate' | 'expired' | 'internal_processing_error' | 'invalid_number' | 'not_found' | 'retries_exhausted' | 'shipping_line_unreachable' | 'unrecognized_response' | 'data_unavailable' | 'scac_auto_detect_failed' | 'null', nullable — If the tracking request has failed, or is currently failing, the last reason we were unable to complete the request. `scac_auto_detect_failed` means `auto_detect_vocc_scac` was set but no supported carrier SCAC could be inferred from the request number. - `request_type` 'bill_of_lading' | 'booking_number' | 'container', required - `scac` string, required - `created_at` string, date-time, required - `updated_at` string, date-time - `is_retrying` boolean - `retry_count` integer, nullable — How many times T49 has attempted to get the shipment from the shipping line - `relationships` object - `tracked_object` object - `data` object, nullable - `id` string, uuid - `type` 'shipment' - `customer` object - `data` object - `id` string, uuid - `type` 'party' - `included` union[] - union - Account - `id` string, uuid, required - `type` 'account', required - `attributes` object, required - `company_name` string, required - ShippingLine - `id` string, uuid, required - `attributes` object, required - `scac` string, required - `name` string, required - `alternative_scacs` string[], required — Additional SCACs which will be accepted in tracking requests - `short_name` string, required - `bill_of_lading_tracking_support` boolean, required - `booking_number_tracking_support` boolean, required - `container_number_tracking_support` boolean, required - `type` 'shipping_line', required ## Other responses - `422` — Unprocessable Entity - `429` — Too Many Requests - You've hit the create tracking requests limit. Please try again in a minute. ## Changes > 54 revisions in range; 6 could not be searched. - **2026-08-14** `663249dcfc09` — 1 info - added the new optional request property `data/attributes/initial_custom_fields` - **2026-07-08** `142a0944ec43` — 1 warning, 2 info - added the new `scac_auto_detect_failed` enum value to the `data/attributes/failed_reason` response property for the response status `201` - added the new optional request property `data/attributes/auto_detect_vocc_scac` - the request property `data/attributes/scac` became optional - **2026-03-26** `90a04ac576b7` — 2 warning, 1 info - removed the optional property `errors/items/meta/tracking_request_id` from the response with the `422` status - added the new `account` enum value to the `included/items/anyOf[subschema #1: Account model]/type` response property for the response status `201` - removed the `container` enum value from the `included/items/anyOf[subschema #1: Account model]/type` response property for the response status `201` - **2025-10-13** `f7305126992d` — 1 info - added the non-success response with the status `429` - **2025-02-19** `f9637d387bc7` — 1 info - added the optional property `data/attributes/updated_at` to the response with the `201` status [Full history](https://skmtc.dev/terminal49/apis/terminal49-api-reference/changes/tracking_requests/post.md) --- [API](https://skmtc.dev/terminal49/apis/terminal49-api-reference.md) · [All operations](https://skmtc.dev/terminal49/apis/terminal49-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/terminal49/terminal49-api-reference/revisions/998a27e39c03/schema)