> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal49 API Quickstart

> Follow the Terminal49 API quickstart to create a tracking request, monitor your first shipment, and retrieve live container and shipment data.

## 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Standard_Carrier_Alpha_Code).
3. **A Terminal49 Account.** If you don't have one yet, [sign up here.](https://app.terminal49.com/register)
4. **An API key.** Sign in to your Terminal49 account and go to your [developer portal page](https://app.terminal49.com/developers/api-keys) to get your API key.

<Tip>
  Not sure which SCAC to use? The [Infer Tracking
  Number](/docs/api-docs/in-depth-guides/auto-detect-carrier) endpoint (Auto-Detect
  Carrier) can identify it from your tracking number.
</Tip>

## 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](/docs/api-docs/useful-info/api-data-sources-availability) for coverage details.

```json POST /tracking_requests theme={null}
{
  "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.

<Note>
  **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](mailto:support@terminal49.com) if you have persistent issues.
</Note>

Use this request to list your recent tracking requests. Replace `YOUR_API_KEY` in the `Authorization` header with your API key.

```json GET /tracking_requests theme={null}
{
  "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.

```json GET /shipments theme={null}
{
  "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.

```json GET /containers theme={null}
{
  "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:

```json POST /webhooks/trigger theme={null}
{
  "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:

```json POST /webhooks theme={null}
{
  "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](/docs/api-docs/in-depth-guides/webhooks).