Skip to main content
In this tutorial, you will create a tracking request. A tracking request tells Terminal49 which shipment or container to monitor. Each tracking request needs two values:
  • A Bill of Lading (BOL), booking number, or container number from the carrier.
  • The carrier Standard Carrier Alpha Code (SCAC). You can see a complete list of supported SCACs in the carrier coverage matrix.
Don’t know the SCAC? Use the Infer Tracking Number endpoint (also called Auto-Detect Carrier) to identify the shipping line from your tracking number.

​
Choose a tracking number

Supported numbers
  1. Master Bill of Lading number from the carrier (recommended)
  2. Booking number from the carrier
  3. Container number
Container number tracking support varies by ocean carrier. Check the carrier coverage matrix to see which carriers support container number tracking.
Unsupported numbers
  • House Bill of Lading (HBOL) numbers
  • Customs entry numbers
  • Seal numbers
  • Internally generated numbers, such as purchase order numbers or customer reference numbers

​
Authentication

Every request in this tutorial sends your API key in the Authorization header: 
Authorization: Token YOUR_API_KEY
If you don’t have an API key yet, get one from the developer portal as described in Start Here.

​
Create a tracking request

Replace YOUR_API_KEY, REQUEST_NUMBER, and SCAC before running this example. The request number must be a master bill of lading, booking, or container number from the carrier. 
curl -X POST "https://api.terminal49.com/v2/tracking_requests" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token YOUR_API_KEY" \
  -d '{
    "data": {
      "type": "tracking_request",
      "attributes": {
        "request_type": "bill_of_lading",
        "request_number": "REQUEST_NUMBER",
        "scac": "SCAC"
      }
    }
  }'
Rate limiting: You can create up to 100 tracking requests per minute.

​
Anatomy of a tracking request response

The response confirms that Terminal49 accepted the request. A new request usually starts with status: "pending" while Terminal49 checks the carrier. 
{
  "data": {
    "id": "478cd7c4-a603-4bdf-84d5-3341c37c43a3",
    "type": "tracking_request",
    "attributes": {
      "request_number": "xxxxxx",
      "request_type": "bill_of_lading",
      "scac": "MAEU",
      "ref_numbers": [],
      "created_at": "2020-09-17T16:13:30Z",
      "updated_at": "2020-09-17T17:13:30Z",
      "status": "pending",
      "failed_reason": null,
      "is_retrying": false,
      "retry_count": null
    },
    "relationships": {
      "tracked_object": {
        "data": null
      }
    },
    "links": {
      "self": "/v2/tracking_requests/478cd7c4-a603-4bdf-84d5-3341c37c43a3"
    }
  }
}
Note that if you try to track the same shipment again, you will receive an error like this: 
{
  "errors": [
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/request_number"
      },
      "title": "Unprocessable Entity",
      "detail": "Request number 'xxxxxxx' with scac 'MAEU' already exists in a tracking_request with a pending or created status",
      "code": "duplicate"
    }
  ]
}
Why so much JSON? (A note on JSON:API)The Terminal49 API is JSON:API compliant. JSON:API libraries can translate the response into a full object model compatible with an ORM, which is powerful but produces larger, more structured payloads. If you parse JSON directly, this can feel verbose. For production use, consider adopting a JSON:API client library to get the most out of the format. For this tutorial, you will work with the data directly.

​
What happens after you create a tracking request

Terminal49 works asynchronously:
  1. You send a tracking request with a shipment identifier and SCAC.
  2. Terminal49 accepts the request and returns a tracking_request with status: "pending".
  3. Terminal49 monitors the carrier and creates shipment and container records as data becomes available.
  4. You list shipments and containers at any time, or receive updates through a webhook.
A webhook is a callback URL that Terminal49 sends POST requests to whenever tracking data changes: you receive tracking_request.succeeded when the shipment is created, or tracking_request.failed if there is a problem. You will register a webhook in step 4 of this path. Until then, you can poll the tracking request as shown below.

​
Check your tracking request status

If you have not set up a webhook yet, poll the Tracking Requests endpoint to check whether your request succeeded or failed. Replace YOUR_API_KEY with your API key. 
curl "https://api.terminal49.com/v2/tracking_requests" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Authorization: Token YOUR_API_KEY"
To check a single request, append the id from the create response: GET /v2/tracking_requests/{id}.

​
Troubleshooting

Tracking request troubleshootingThe most common issue people encounter is that they are entering the wrong number.Check that you are entering a Bill of Lading number, booking number, or container number — not an internal reference from your company or freight forwarder. Verify the number by going to the carrier’s website and tracking the shipment with it. If that works and the SCAC is supported by Terminal49, you should be able to track it through the API.If you are unsure of the correct SCAC, try the Infer Tracking Number endpoint first.Sometimes the issue is on the shipping line’s side. Temporary network problems, unpopulated manifests, and other issues can occur. See Tracking Request Retrying for how Terminal49 handles these cases.
You can always email us at support@terminal49.com if you have persistent issues.

​
Next up: get your shipments

Now that you’ve made a tracking request, the next step is to list your shipments and retrieve the tracking data.

List shipments and containers

Retrieve the shipment and container records Terminal49 created for you.
See How to initiate shipment tracking on Terminal49 for other ways of initiating shipment tracking.