Quick Start Guide

​

Before You Begin

You’ll need a 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.

​

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.

{
  "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

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.

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.

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

** 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"
  }
}

​

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.

{
  "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.

{
  "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 true power of Terminal49’s API is that it is asynchronous. You can register a Webhook, which is essentially a callback URL that our systems HTTP Post to when there are updates.

To try this, you will need to first set up a URL on the open web to receive POST requests. Once you have done this, you’ll be able to receive status updates from containers and shipments as they happen, which means you don’t need to poll us for updates; we’ll notify you.

** 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.

{
  "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}"
}