Skip to main content
The Terminal49 API gives you a single integration to track Bills of Lading (BOLs), bookings, and container numbers across global ocean carriers. You get complete import milestones — from empty-out at origin to empty-return at destination, including rail data in North America.

​
Prerequisites

Before making API calls, you need:

​
Base URL

​
Authentication

Include your API key in the Authorization header, prefixed with Token (not Bearer):
Replace YOUR_API_KEY with the raw key value from the developer portal — no quotes, no Bearer prefix, and no extra whitespace. A 401 Unauthorized response with "Terminal49 API key could not be verified" means the key is missing, malformed, revoked, or truncated when it was copied.
The full API key value is only shown once, right after you create it. Copy the complete token from that screen and store it in a secret manager before navigating away — after that, the value is masked and cannot be revealed again. If you lost the full value, create a new key, copy it immediately, then delete the older key.

​
Restricted API access on Free plans

Free-plan accounts can authenticate and create tracking requests, but read endpoints are gated. A valid key on a restricted account returns 401 Unauthorized with "You do not have permissions for using the API, except for creating tracking requests" when you call any endpoint other than POST /v2/tracking_requests. To read tracking data (GET /v2/shipments, GET /v2/containers, GET /v2/tracking_requests/{id}, and other endpoints), your account needs full API access enabled. Full API access is not automatic on the Free plan. Contact support@terminal49.com to enable a 7-day API trial, or see Pricing for plans that include ongoing API read access.

​
Request and response format

  • The API follows the JSON:API specification
  • All responses return application/vnd.api+json content type
  • Requests that include a body should set Content-Type: application/vnd.api+json
  • JSON:API client libraries are available in most languages

​
Example response

​
Rate limits

Some endpoints have their own rate-limit bucket. For example, Infer Tracking Number allows 200 requests per minute, Create Tracking Request allows 100 requests per minute, and Refresh Container allows 10 requests per minute. See the rate limiting guide for endpoint-specific limits, retry semantics, and best practices.
Use webhooks instead of polling to receive real-time updates. This keeps you well within rate limits and gives you faster data.

​
Core resources

Tracking Requests

Create and manage tracking requests by BOL, booking, or container number.

Shipments

Retrieve shipment details, ETAs, and milestones.

Containers

Container-level statuses, transport events, and map data.

Webhooks

Subscribe to real-time push notifications when shipment data changes.

​
Supporting resources

Custom Fields

Attach your own metadata to shipments and containers.

Shipping Lines

Look up supported carriers and SCACs.

Vessels

Vessel details and future position data.

Ports

Port lookups by UN/LOCODE.

Terminals

Terminal details at destination ports.

Parties

Manage customer and partner references.