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

Use the request example below as a starting point, or copy the same values into Postman or cURL.
  1. Replace YOUR_API_KEY in the Authorization header with your API key.
  2. Replace request_number and scac with your shipment details. The request number must be a shipping line booking number, master bill of lading number, or container number. The SCAC must be a shipping line SCAC. See API Data Sources for coverage details.
http
{
  "method": "post",
  "url": "https://api.terminal49.com/v2/tracking_requests",
  "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"
    }
  }
}

​
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.
Use this request to list your recent tracking requests. Replace YOUR_API_KEY in the Authorization header 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. Use this request to list tracked shipments. Replace YOUR_API_KEY in the Authorization header 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. Use this request to list tracked containers. Replace YOUR_API_KEY in the Authorization header 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. Choose the events you want to subscribe to (for example vessel departed, arrived, or discharged). Terminal49 sends those events to your webhook endpoint as soon as they happen. You can test your endpoint before creating the actual webhook by sending a sample notification with the Trigger endpoint:
http
{
  "method": "post",
  "url": "https://api.terminal49.com/v2/webhooks/trigger",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Token YOUR_API_KEY"
  },
  "body": {
    "url": "https://webhook.site/",
    "event": "container.transport.vessel_arrived",
    "secret": "optional-test-secret"
  }
}
Trigger sends an example payload for the event you choose. Once tested, create the actual webhook to receive the real notifications as they happen:
http
{
  "method": "post",
  "url": "https://api.terminal49.com/v2/webhooks",
  "headers": {
    "Content-Type": "application/vnd.api+json",
    "Authorization": "Token YOUR_API_KEY"
  },
  "body": {
    "data": {
      "type": "webhook",
      "attributes": {
        "url": "https://webhook.site/",
        "active": true,
        "events": ["container.transport.vessel_arrived"]
      }
    }
  }
}
Learn more about Webhooks.