Create a Tracking Request

Submit a new tracking request to monitor ocean shipments via bill of lading, booking number, or container number.

POST /tracking_requests

Create a tracking request

cURL

curl --request POST \
  --url https://api.terminal49.com/v2/tracking_requests \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {
    "attributes": {
      "request_type": "bill_of_lading",
      "request_number": "MEDUFR030802",
      "ref_numbers": [
        "PO12345",
        "HBL12345",
        "CUSREF1234"
      ],
      "shipment_tags": [
        "camembert"
      ],
      "scac": "MSCU"
    },
    "relationships": {
      "customer": {
        "data": {
          "id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
          "type": "party"
        }
      }
    },
    "type": "tracking_request"
  }
}
'

201

{
  "data": {
    "id": "ba4cb904-827f-4038-8e31-1e92b3356218",
    "type": "tracking_request",
    "attributes": {
      "request_number": "MEDUFR030802",
      "request_type": "bill_of_lading",
      "scac": "MSCU",
      "ref_numbers": [],
      "created_at": "2020-04-04T16:13:35-07:00",
      "updated_at": "2020-04-04T17:13:35-07:00",
      "status": "pending",
      "failed_reason": null
    },
    "relationships": {
      "tracked_object": {
        "data": null
      },
      "customer": {
        "data": {
          "id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
          "type": "party"
        }
      }
    },
    "links": {
      "self": "/v2/tracking_requests/ba4cb904-827f-4038-8e31-1e92b3356218"
    }
  }
}

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

Track by Bill of Lading

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.

Track by Container Number

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.

Using Test Numbers

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.

Error Handling

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.

Show Properties

data.id · string

ID of the linked shipment that you can use to retrieve full shipment details.

data.type · string

Always “shipment” for successful tracking requests.

Related Webhook Events

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.

Related Guides & Tutorials

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

My tracking request is stuck in 'pending' status

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 [e-mail].

Tracking request failed with 'not_found'

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.

I received a duplicate error

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

3. You can access the existing shipment data instead of creating a new tracking request.

Track by Booking Number

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)

Including Reference Numbers

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

Adding Tags

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

Associating with a Customer

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.

Authorizations

Authorization · string · header · required

Token YOUR_API_TOKEN

The APIs require authentication to be done using header-based API Key and Secret Authentication.

API key and secret are sent va the Authorization request header.

You send your API key and secret in the following way:

Authorization: Token YOUR_API_KEY

Body

application/json

Create a shipment tracking request

data · object

Show child attributes

Response

201

application/json

Tracking Request Created

data · Tracking Request · object

Show child attributes

included · (Account model · object | Shipping line model · object)[]

Account model

Shipping line model

Show child attributes