---
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, you create a new tracking request. 
Two attributes are required to track a shipment. A `bill of lading/booking number` and a shipping line `SCAC`. 

Once a tracking request is created we will attempt to fetch the shipment details and it's related containers from the shipping line. If the attempt is successful we will create in 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 notificaiton will only be sent  if you have  atleast one active webhook.

## 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, required
      - `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
    - `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' | 'null', nullable — If the tracking request has failed, or is currently failing, the last reason we were unable to complete the request
      - `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` 'container', 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

## Changes

- **2025-02-19** `f9637d387bc7` — 1 info
  - added the optional property `data/attributes/updated_at` to the response with the `201` status
- **2025-01-24** `b96cb1031218` — 2 info
  - added the new optional request property `data/relationships`
  - added the optional property `data/relationships/customer` to the response with the `201` status

[Change 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/eecd2d93fbbd/schema)