Identify Your Carrier with the Infer API

Use the Terminal49 Infer API to identify a carrier SCAC from a bill of lading or container number before you create a tracking request.

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, Terminal49 auto-suggests 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) used here is the shipping line SCAC for tracking — that is, the carrier operating the move you’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

1. You submit a tracking number

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

2. We analyze the pattern

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

3. You get the SCAC and confidence score

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

4. Create a successful tracking request

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

Examples by number type

Container 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

Request

{
  "number": "MSCU1234567"
}

For container numbers, Terminal49 uses 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

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

Request

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

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

Example Input: 987654321

Request

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

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);
}

Python

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

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 Terminal49 supports and their data availability

Tracking Request Lifecycle

Learn what happens after you submit a tracking request