Skip to main content

​
Endpoint Purpose

Submitting a tracking request tells Terminal49 to start monitoring a specific shipment for you. This is typically the first step in the tracking workflow.

​
Business Use Cases

  • Initial Tracking Setup: Start tracking a new container shipment when you receive a bill of lading or booking confirmation.
  • Customer Onboarding: Quickly set up tracking for a customer’s shipments when they provide their shipping documents.
  • Bulk Import: Programmatically submit multiple tracking requests to monitor your entire inventory in transit.

​
Example Scenarios

Request
{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MAEU9736478",
      "scac": "MAEU"
    }
  }
}
Response
{
  "data": {
    "id": "b9c6a3e0-411e-4378-b93c-aacea42a673e",
    "type": "tracking_request",
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MAEU9736478",
      "scac": "MAEU",
      "status": "pending",
      "failed_reason": null,
      "created_at": "2023-05-15T14:23:12Z",
      "updated_at": "2023-05-15T14:23:12Z"
    },
    "relationships": {
      "shipment": {
        "data": null
      }
    }
  }
}
Notes:
  • The bill of lading is typically the most reliable identifier for tracking shipments.
  • The status will initially be pending while Terminal49 processes your request.
  • Once processing completes, you’ll receive a webhook notification and the status will change to succeeded or failed.
Request
{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_type": "container",
      "request_number": "MSCU1234567",
      "scac": "MSCU"
    }
  }
}
Response
{
  "data": {
    "id": "f7c9b5d2-311e-4378-a91c-bbcea42a785f",
    "type": "tracking_request",
    "attributes": {
      "request_type": "container",
      "request_number": "MSCU1234567",
      "scac": "MSCU",
      "status": "pending",
      "failed_reason": null,
      "created_at": "2023-05-15T15:45:22Z",
      "updated_at": "2023-05-15T15:45:22Z"
    },
    "relationships": {
      "shipment": {
        "data": null
      }
    }
  }
}
Notes:
  • Container number tracking support varies between carriers. Refer to the Carrier Data Matrix to verify support.
  • Container numbers should include the carrier prefix (e.g., MSCU for MSC containers).
  • Container tracking can sometimes fail if the container is very new or not yet associated with a booking in the carrier’s system.
Request
{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "TEST-TR-SUCCEEDED",
      "scac": "TEST"
    }
  }
}
Response
{
  "data": {
    "id": "e8d7c6b5-211d-4378-a81b-aacfa42a895e",
    "type": "tracking_request",
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "TEST-TR-SUCCEEDED",
      "scac": "TEST",
      "status": "pending",
      "failed_reason": null,
      "created_at": "2023-05-15T16:30:45Z",
      "updated_at": "2023-05-15T16:30:45Z"
    },
    "relationships": {
      "shipment": {
        "data": null
      }
    }
  }
}
Notes:
  • Using test numbers is perfect for development and testing your integration.
  • TEST-TR-SUCCEEDED will always trigger a successful tracking response.
  • TEST-TR-FAILED will always trigger a failed tracking response.
  • These test numbers will trigger corresponding webhook events for complete testing.
Request
{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "INVALID-FORMAT",
      "scac": "UNKNOWN"
    }
  }
}
Response
{
  "errors": [
    {
      "status": "422",
      "title": "Invalid SCAC",
      "detail": "The SCAC 'UNKNOWN' is not supported.",
      "source": {
        "pointer": "/data/attributes/scac"
      }
    }
  ]
}
Notes:
  • This example shows a validation error for an invalid SCAC code.
  • Common errors include invalid SCAC codes, improperly formatted request numbers, or duplicate tracking requests.
  • For a complete list of supported SCACs, refer to the Carrier Data Matrix.

​
Key Response Fields

​
id
string
Unique identifier for the tracking request. Store this to check status later.
​
status
string
Current status of the tracking request. Possible values:
  • pending: Request is being processed
  • succeeded: Container/shipment located and tracking established
  • failed: Unable to track the shipment (see failed_reason)
  • awaiting_manifest: Bill of lading is valid but not yet available in the carrier’s system
  • tracking_stopped: Tracking has been stopped for this request
​
failed_reason
string
If status is “failed”, this field provides the reason. Common values:
  • duplicate: Shipment already exists in Terminal49
  • not_found: Shipping line couldn’t find the tracking number
  • retries_exhausted: Maximum retries reached without success
  • invalid_number: Improperly formatted tracking number
See the Tracking Request Lifecycle guide for a complete list of failure reasons.
​
relationships.shipment
object
When the tracking request succeeds, this contains a reference to the created shipment.
When creating a tracking request, you may receive the following webhook events:

tracking_request.succeeded

Sent when Terminal49 successfully locates your shipment and begins tracking it. The notification includes details about the created shipment and its containers.

tracking_request.failed

Sent when Terminal49 is unable to locate your shipment after all retry attempts. Includes the failed_reason to help troubleshoot.

tracking_request.awaiting_manifest

Sent when the bill of lading number is valid but the shipment data is not yet available in the carrier’s system. Terminal49 will continue checking daily.

Tracking Request Lifecycle

Learn about the full lifecycle of a tracking request, including all possible statuses and failure reasons.

Setting Up Webhooks

Learn how to set up webhooks to receive real-time notifications about your tracking requests.

Test Numbers

Complete list of test tracking numbers you can use during development.

Bulk Tracking Tutorial

Learn how to efficiently submit and manage multiple tracking requests.

​
Troubleshooting

Problem: Your tracking request has been in “pending” status for an extended period.Solution:
  1. Terminal49 retries tracking requests up to 14 times over 24 hours.
  2. Check that the SCAC and request number are correct.
  3. For bill of lading numbers, note that they may remain in “awaiting_manifest” status for up to 7 days.
  4. If the issue persists beyond 24 hours, contact support@terminal49.com.
Problem: Your tracking request failed with reason “not_found”.Solution:
  1. Verify the tracking number format is correct (no spaces, proper prefixes).
  2. Confirm you’re using the correct SCAC code for the carrier.
  3. For newly issued bills of lading, try again in 24-48 hours as it may take time to appear in the carrier’s system.
  4. If using a container number, check if the carrier supports container tracking in the Carrier Data Matrix.
Problem: Your tracking request failed with reason “duplicate”.Solution:
  1. The shipment is already being tracked in Terminal49.
  2. Use GET /shipments with a filter to find the existing shipment:
GET /shipments?filter[bill_of_lading_number]=MAEU9736478
  1. You can access the existing shipment data instead of creating a new tracking request.
Scenario: You want to create a tracking request using a booking number.Example:
{
  "data": {
    "attributes": {
      "request_type": "booking_number",
      "request_number": "OOLU8324567",
      "scac": "OOLU"
    },
    "type": "tracking_request"
  }
}
Notes:
  • Booking numbers are typically issued by the carrier early in the shipping process
  • Using booking numbers allows you to start tracking earlier in the shipping lifecycle
  • Booking number format varies by carrier (e.g., OOLU prefix for ONE Line bookings)
Scenario: You want to add your own reference numbers to help identify the shipment.Example:
{
  "data": {
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MEDUFR030802",
      "scac": "MSCU",
      "ref_numbers": [
        "PO12345",
        "HBL12345",
        "INV9876"
      ]
    },
    "type": "tracking_request"
  }
}
Notes:
  • Reference numbers can include purchase orders, house bills of lading, invoice numbers, etc.
  • You can add multiple reference numbers to a single tracking request
  • These numbers will be searchable later through the API and UI
  • You can use reference numbers to link shipments to your internal systems
Scenario: You want to categorize your shipments with tags for easier filtering.Example:
{
  "data": {
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MAEU9736478",
      "scac": "MAEU",
      "shipment_tags": [
        "priority",
        "electronics",
        "q2-2023"
      ]
    },
    "type": "tracking_request"
  }
}
Notes:
  • Tags provide a flexible way to group and categorize shipments
  • Common uses include priority levels, product categories, or time periods
  • Tags can be used for filtering when listing shipments
  • You can add or remove tags later using the Edit Shipment endpoint
Scenario: You’re tracking shipments on behalf of your customers and want to associate shipments with specific customers.Example:
{
  "data": {
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MAEU9736478",
      "scac": "MAEU"
    },
    "relationships": {
      "customer": {
        "data": {
          "id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
          "type": "party"
        }
      }
    },
    "type": "tracking_request"
  }
}
Notes:
  • The customer must first be created using the Parties API
  • The customer ID is used to link the shipment to the specific customer
  • This association enables filtering shipments by customer
  • Customer information will be included in webhook notifications when using appropriate includes
  • See the Adding Customer guide for more details
For the fastest tracking setup, use the master bill of lading (MBL) number from the carrier. House bills of lading (HBL) are not supported.
Container number tracking is not supported by all carriers. Always check the Carrier Data Matrix before implementing container tracking.