Auto-Detect Carrier | Terminal49 API Documentation

Beta Feature — This guide covers the Infer Number API, currently in beta. The API is stable for production use, but features may expand based on feedback.

Every tracking request requires two things: your tracking number and the shipping line’s (carrier’s) SCAC code. But what if you don’t know the SCAC? That’s where the Infer API comes in.

Already using the Terminal49 Dashboard?

You’ve seen this feature in action — when you enter a number, we auto-suggest the carrier. Now this same intelligence is available via API.

Why SCAC Matters

To track a shipment or container, Terminal49 needs to know which shipping line to ask (also called the vessel-operating common carrier (VOCC)). The SCAC (Standard Carrier Alpha Code) we use here is the shipping line SCAC for tracking — i.e., the carrier operating the move we’re querying for events and shipment data.

You Have	You Need	The Challenge
Bill of Lading: `MAEU123456789`	Shipping line SCAC (VOCC SCAC)	Many MBOLs do not include a prefix, and even when they do, it may not reliably identify the shipping line you need for tracking.
Container: `WHLU1234560`	Shipping line SCAC (VOCC SCAC)	The container owner code / leasing company is not always the carrier moving it, so the prefix alone is not enough.
Booking: `987654321`	Shipping line SCAC (VOCC SCAC)	Booking formats vary widely and often contain no carrier identifier.

Without the correct shipping line SCAC (VOCC SCAC), your tracking request can fail even if the number is valid. The Infer API predicts the shipping line SCAC + number type to increase the likelihood your tracking request succeeds.

How the Infer API Helps

Submit any tracking number, and the API returns:

The predicted shipping line (SCAC) — so you don’t have to guess
The number type — container, bill of lading, or booking
Validation results — catches typos and invalid formats before you submit

You submit a tracking number

Just the number — no need to specify the shipping line or type

We analyze the pattern

Our system uses machine learning and historical data from millions of shipments to predict the shipping line.

You get the SCAC and confidence score

Use high-confidence results automatically, or prompt users to confirm

Create a successful tracking request

With the right SCAC, your tracking request is far more likely to succeed

Examples by Number Type

Container Number
Bill of Lading
Booking Number

Container numbers follow the ISO 6346 format. While the first three letters (owner code) often indicate the owner, the container might be moved by a different shipping line (VOCC).Our system analyzes the number against tens of millions of historical records to predict which shipping line is moving the container.Example Input: MSCU1234567

{
  "number": "MSCU1234567"
}

For container numbers, we use historical data to identify the shipping line with high accuracy (9/10 times). Always check the decision field to know if you should ask the user for confirmation.

What to do next:

# Create tracking request with the detected SCAC
POST /tracking_requests
{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_number": "MSCU1234567",
      "scac": "MSCU",
      "request_type": "container"
    }
  }
}

Bill of lading numbers vary by carrier. Some contain prefixes, but others don’t. The API uses machine learning to identify the carrier pattern.Example Input: MAEU123456789

{
  "number": "MAEU123456789"
}

Maersk BLs typically start with MAEU, but other carriers may not have prefixes. The API analyzes the full format.

What to do next:

# Create tracking request with the detected SCAC
POST /tracking_requests
{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_number": "MAEU123456789",
      "scac": "MAEU",
      "request_type": "bill_of_lading"
    }
  }
}

Booking numbers are the hardest to identify — they often don’t contain carrier identifiers.Example Input: 987654321

{
  "number": "987654321"
}

When decision is needs_confirmation, show the suggestion but ask the user to verify. Display the candidates list as options.

What to do next:

# Show user the suggested carrier and candidates
# After user confirms, create tracking request
POST /tracking_requests
{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_number": "987654321",
      "scac": "HLCU",
      "request_type": "booking"
    }
  }
}

Understanding the Response

Decision Types Explained

The decision field tells you how confident the prediction is and what action to take:

Decision	When it’s used	What to do
`auto_select`	Confidence ≥ 95%	✅ Safe to use automatically without user confirmation
`needs_confirmation`	Confidence 70-95%	⚠️ Show suggestion, ask user to confirm
`no_prediction`	Confidence < 70% or unknown	❌ User must select carrier manually

For the best user experience, always handle all three decision types. Even when no_prediction is returned, you can still show the list of candidates as suggestions.

Validation Fields

The API validates numbers before returning predictions:

Field	Description
`is_valid`	`true` if format is valid, `false` if invalid, `null` if unknown
`check_digit_passed`	For containers: ISO 6346 check digit verification
`reason`	If invalid, explains why (e.g., “Invalid check digit”)

Invalid numbers may still return a carrier prediction, but you should validate the format before creating a tracking request.

Full Response Schema

Field	Type	Description
`number_type`	string	Detected type: `container`, `bill_of_lading`, or `booking`
`shipping_line.decision`	string	Confidence level for the prediction
`shipping_line.selected`	object	Best match: `scac`, `name`, `confidence`
`shipping_line.candidates`	array	All possible matches, ranked by confidence

See the API Reference for complete schema details.

Integration Guide

For developers implementing this API, here are code examples in different languages:

JavaScript
Python
cURL

async function getCarrierForNumber(trackingNumber, apiKey) {
  const response = await fetch(
    "https://api.terminal49.com/v2/tracking_requests/infer_number",
    {
      method: "POST",
      headers: {
        Authorization: `Token ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ number: trackingNumber }),
    }
  );

const { data } = await response.json();
const { decision, selected, candidates } = data.attributes.shipping_line;

return {
scac: selected?.scac,
carrier: selected?.name,
confidence: selected?.confidence,
autoSelect: decision === "auto_select",
needsConfirmation: decision === "needs_confirmation",
candidates: candidates,
};
}

// Usage
const result = await getCarrierForNumber("MSCU1234567", "YOUR_API_KEY");
if (result.autoSelect) {
// Auto-fill carrier dropdown
carrierDropdown.value = result.scac;
} else if (result.needsConfirmation) {
// Show suggestion with confirmation prompt
showCarrierSuggestion(result.carrier, result.candidates);
}

import requests

def get_carrier_for_number(tracking_number: str, api_key: str) -> dict:
    """Get carrier prediction for a tracking number."""
    response = requests.post(
        'https://api.terminal49.com/v2/tracking_requests/infer_number',
        headers={
            'Authorization': f'Token {api_key}',
            'Content-Type': 'application/json'
        },
        json={'number': tracking_number}
    )

    result = response.json()
    shipping_line = result['data']['attributes']['shipping_line']

    return {
        'scac': shipping_line['selected']['scac'] if shipping_line.get('selected') else None,
        'carrier': shipping_line['selected']['name'] if shipping_line.get('selected') else None,
        'confidence': shipping_line['selected']['confidence'] if shipping_line.get('selected') else None,
        'auto_select': shipping_line['decision'] == 'auto_select',
        'needs_confirmation': shipping_line['decision'] == 'needs_confirmation',
        'candidates': shipping_line.get('candidates', [])
    }

# Usage
result = get_carrier_for_number("MSCU1234567", "YOUR_API_KEY")
if result['auto_select']:
    # Auto-fill carrier dropdown
    carrier_dropdown.value = result['scac']
elif result['needs_confirmation']:
    # Show suggestion with confirmation prompt
    show_carrier_suggestion(result['carrier'], result['candidates'])

curl -X POST https://api.terminal49.com/v2/tracking_requests/infer_number \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": "MSCU1234567"}'

Rate Limits

Setting	Value
Requests per minute	200
Rate limit header	`Retry-After` (seconds)

Rate limit errors return HTTP 429 with a Retry-After header. Respect this header to avoid extended throttling.

What’s Next?

Infer Number API Reference

Full API specification with request/response schemas and try it in the playground

Create a Tracking Request

Use the detected SCAC to start tracking your shipment

Supported Carriers

See which carriers we support and their data availability

Tracking Request Lifecycle

Learn what happens after you submit a tracking request

Getting Started

In Depth Guides

Useful Info

Shipments

Tracking Requests

Webhooks

Webhook Notifications

Containers

Shipping Lines

Metro Areas

Ports

Vessels

Terminals

Parties

Identify Your Carrier with the Infer API

Already using the Terminal49 Dashboard?

Why SCAC Matters

How the Infer API Helps

Examples by Number Type

Understanding the Response

Integration Guide

Rate Limits

What’s Next?

Infer Number API Reference

Create a Tracking Request

Supported Carriers

Tracking Request Lifecycle

Getting Started

In Depth Guides

Useful Info

Shipments

Tracking Requests

Webhooks

Webhook Notifications

Containers

Shipping Lines

Metro Areas

Ports

Vessels

Terminals

Parties

Already using the Terminal49 Dashboard?

​Why SCAC Matters

​How the Infer API Helps

​Examples by Number Type

​Understanding the Response

​Integration Guide

​Rate Limits

​What’s Next?

Infer Number API Reference

Create a Tracking Request

Supported Carriers

Tracking Request Lifecycle

Why SCAC Matters

How the Infer API Helps

Examples by Number Type

Understanding the Response

Integration Guide

Rate Limits

What’s Next?