Skip to main content

​
Before you begin

You need four things to get started.
  1. A Bill of Lading (BOL) number. This is issued by your carrier. BOL numbers are found on your bill of lading document. Ideally, this will be a shipment that is currently on the water or in terminal, but this is not necessary.
  2. The SCAC of the carrier that issued your bill of lading. The Standard Carrier Alpha Code of your carrier is used to identify carriers in computer systems and in shipping documents. You can learn more about these here.
  3. A Terminal49 Account. If you don’t have one yet, sign up here.
  4. An API key. Sign in to your Terminal49 account and go to your developer portal page to get your API key.
Not sure which SCAC to use? The Auto-Detect Carrier API can identify it from your tracking number.

​
Track a shipment

You can try this using the embedded request maker below, or using Postman.
  1. Try it below. Click “Headers” and replace YOUR_API_KEY with your API key. In the authorization 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, include a cURL template, by clicking the “Code Generation” tab in the Request Maker.
http
{
  "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}"
}

​
Check your tracking request succeeded

If you have not set up a webhook to receive status updates from the Terminal49 API, you need to poll manually to check whether the tracking request succeeded or failed.

​
Tracking request troubleshooting

The most common issue is 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. Email support@terminal49.com if you have persistent issues.
** Try it below. Click “Headers” and replace <YOUR_API_KEY> with your API key.**
http
{
  "method": "get",
  "url": "https://api.terminal49.com/v2/tracking_requests",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  }
}

​
List your tracked shipments

If your tracking request was successful, you will now be able to list your tracked shipments. Try it below. Click “Headers” and replace YOUR_API_KEY with your API key. Sometimes it may take a while for the tracking request to show up, but usually no more than a few minutes. If you had trouble adding your first shipment, try adding a few more.
http
{
  "method": "get",
  "url": "https://api.terminal49.com/v2/shipments",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  }
}

​
List all your tracked containers

You can also list out all of your containers, if you’d like to track at that level. Try it after replacing <YOUR_API_KEY> with your API key.
http
{
  "method": "get",
  "url": "https://api.terminal49.com/v2/containers",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  }
}

​
Listening for updates with webhooks

The real power of Terminal49’s API is that it is asynchronous. You can register a webhook — a callback URL that Terminal49 sends HTTP POST requests to when updates occur. To try this, first set up a URL on the open web to receive POST requests. Once configured, you receive status updates from containers and shipments as they happen, so you do not need to poll for updates. ** Try it below. Click “Headers” and replace YOUR_API_KEY with your API key.** Once this is done, any changes to shipments and containers you’re tracking in step 2 will now be sent to your webhook URL as Http POST Requests. View the “Code Generation” button to see sample code.
http
{
  "method": "post",
  "url": "https://api.terminal49.com/v2/webhooks",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  },
  "body": "{\r\n  \"data\": {\r\n    \"type\": \"webhook\",\r\n    \"attributes\": {\r\n      \"url\": \"https:\/\/webhook.site\/\",\r\n      \"active\": true,\r\n      \"events\": [\r\n        \"*\"\r\n      ]\r\n    }\r\n  }\r\n}"
}