​
What is a Tracking Request?

Your tracking request includes two pieces of data:

  • Your Bill of Lading, Booking number, or container number from the carrier.
  • The SCAC code for that carrier.

You can see a complete list of supported SCACs in row 2 of the Carrier Data Matrix.

​
What sort of numbers can I track?

Supported numbers

  1. Master Bill of Lading from the carrier (recommended)
  2. Booking number from the carrier
  3. Container number
  • Container number tracking support across ocean carriers is sometimes more limited. Please refer to the Carrier Data Matrix to see which SCACs are compatible with Container number tracking.

Unsupported numbers

  • House Bill of Lading numbers (HBOL)
  • Customs entry numbers
  • Seal numbers
  • Internally generated numbers, for example PO numbers or customer reference numbers.

​
How do I use Tracking Requests?

Terminal49 is an event-based API, which means that the API can be used asynchronously. In general the data flow is:

  1. You send a tracking request to the API with your Bill of Lading number and SCAC.
  2. The API will respond that it has successfully received your Tracking Request and return the Shipment’s data that is available at that time.
  3. After you have submitted a tracking request, the shipment and all of the shipments containers are tracked automatically by Terminal49.
  4. You will be updated when anything changes or more data becomes available. Terminal49 sends updates relating to your shipment via posts to the webhook you have registered. Generally speaking, updates occur when containers reach milestones. ETA updates can happen at any time. As the ship approaches port, you will begin to receive Terminal Availability data, Last Free day, and so forth.
  5. At any time, you can directly request a list of shipments and containers from Terminal49, and the API will return current statuses and information. This is covered in a different guide.

​
How do you send me the data relating to the tracking request?

You have two options. First, you can poll for updates. This is the way we’ll show you first.

You can poll the GET /tracking_request/{id} endpoint to see the status of your request. You just need to track the ID of your tracking request, which is returned to you by the API.

Second option is that you can register a webhook and the API will post updates when they happen. This is more efficient and therefore preferred. But it also requires some work to set up.

A Webhook is another name for a web-based callback URL, or a HTTP Push API. Webhooks provide a method for an API to post a notification to your service. Specifically, a webhook is simply a URL that can receive HTTP Post Requests from the Terminal49 API.

When we successfully lookup the Bill of Lading with the Carrier’s SCAC, we will create a shipment, and send the event tracking_request.succeeded to your webhook endpoint with the associated record.

If we encounter a problem we’ll send the event tracking_request.failed.

Tracking Request Diagram

​
Authentication

The API uses Bearer Token style authentication. This means you send your API Key as your token in every request.

To get your API token to Terminal49 and go to your account API settings

The token should be sent with each API request in the Authentication header:

Support dev@terminal49.com

Authorization: Token YOUR_API_KEY

​
How to Create a Tracking Request

Here is javascript code that demonstates sending a tracking request

fetch("https://api.terminal49.com/v2/tracking_requests", {
  "method": "POST",
  "headers": {
    "content-type": "application/vnd.api+json",
    "authorization": "Token YOUR_API_KEY"
  },
  "body": {
    "data": {
      "attributes": {
        "request_type": "bill_of_lading",
        "request_number": "",
        "scac": ""
      },
      "type": "tracking_request"
    }
  }
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});

​
Anatomy of a Tracking Request Response

Here’s what you’ll see in a Response to a tracking request.

{
    "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",
            "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, 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, which means that there are nifty libraries which can translate JSON into a fully fledged object model that can be used with an ORM. This is very powerful, but it also requires a larger, more structured payload to power the framework. The tradeoff, therefore, is that it’s less convenient if you’re parsing the JSON directly. Ultimately we strongly recommend you set yourself up with a good library to use JSON API to its fullest extent. But for the purposes of understanding the API’s fundamentals and getting your feet wet, we’ll work with the data directly.

​
Try It: Make a Tracking Request

Try it using the request maker below!

  1. Enter your API token in the autorization header value.
  2. Enter a value for the request_number and scac. The request number has to be a shipping line booking or master bill of lading number. The SCAC has to be a shipping line scac (see data sources to get a list of valid SCACs)

Note that you can also access sample code in multiple languages by clicking the “Code Generation” below.

Tracking Request Troubleshooting

The most common issue people encounter is that they are entering the wrong number.

Please check that you are entering the Bill of Lading number, booking number, or container number and not internal reference at your company or by your frieght forwarder. You can the number you are supplying by going to a carrier’s website and using their tools to track your shipment using the request number. If this works, and if the SCAC is supported by T49, you should able to track it with us.

It is entirely possible that’s neither us nor you but the shipping line is giving us a headache. Temporary network problems, not populated manifest and other things happen! You can read on how are we handling them in the Tracking Request Retrying section.

You can always email us at support@terminal49.com if you have persistent issues.

{
  "method": "post",
  "url": "https://api.terminal49.com/v2/tracking_requests",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  },
  "body": "{\r\n  \"data\": {\r\n    \"attributes\": {\r\n      \"request_type\": \"bill_of_lading\",\r\n      \"request_number\": \"\",\r\n      \"scac\": \"\"\r\n    },\r\n    \"type\": \"tracking_request\"\r\n  }\r\n}"
}

​
Try It: List Your Active Tracking Requests

We have not yet set up a webook to receive status updates from the Terminal49 API, so we will need to manually poll to check if the Tracking Request has succeeded or failed.

Try it below. Click “Headers” and replace <YOUR_API_KEY> with your API key.

{
  "method": "get",
  "url": "https://api.terminal49.com/v2/tracking_requests",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  }
}

​
Next Up: Get your Shipments

Now that you’ve made a tracking request, let’s see how you can list your shipments and retrieve the relevant data.

Go to this page to see different ways of initiating shipment tracking on Terminal49.

Was this page helpful?

1. Start Here3. List Your Shipments & Containers