Create a Tracking Request

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",
      "initial_custom_fields": {
        "shipment": [
          {
            "api_slug": "booking_reference",
            "value": "BOOK-2026-001"
          }
        ],
        "containers": [
          {
            "api_slug": "po_number",
            "value": "PO-123",
            "number": "MSCU1234567"
          },
          {
            "api_slug": "po_number",
            "value": "PO-999",
            "number": "TCLU7654321"
          },
          {
            "api_slug": "customs_broker",
            "value": "Acme Brokerage"
          },
          {
            "api_slug": "seal_number",
            "value": "SEAL-0001",
            "number": ""
          }
        ]
      },
      "ref_numbers": [
        "PO12345",
        "HBL12345",
        "CUSREF1234"
      ],
      "shipment_tags": [
        "camembert"
      ],
      "scac": "MSCU"
    },
    "relationships": {
      "customer": {
        "data": {
          "id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
          "type": "party"
        }
      }
    },
    "type": "tracking_request"
  }
}
'

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

{
  "errors": [
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/scac"
      },
      "title": "Unprocessable Entity",
      "detail": "Scac can't be blank",
      "code": "blank"
    },
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/scac"
      },
      "title": "Unprocessable Entity",
      "detail": "Scac 'XXXX' is not recognized",
      "code": "blank"
    },
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/scac"
      },
      "title": "Unprocessable Entity",
      "detail": "Scac 'UALC' is not supported. We do not currently integrate with Universal Africa Lines",
      "code": "blank"
    },
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/request_number"
      },
      "title": "Unprocessable Entity",
      "detail": "Request number can't be blank",
      "code": "blank"
    }
  ]
}

{
  "errors": [
    {
      "status": "429",
      "title": "Too Many Requests",
      "detail": "You've hit the create tracking requests limit. Please try again in a minute."
    }
  ]
}

POST

tracking_requests

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",
      "initial_custom_fields": {
        "shipment": [
          {
            "api_slug": "booking_reference",
            "value": "BOOK-2026-001"
          }
        ],
        "containers": [
          {
            "api_slug": "po_number",
            "value": "PO-123",
            "number": "MSCU1234567"
          },
          {
            "api_slug": "po_number",
            "value": "PO-999",
            "number": "TCLU7654321"
          },
          {
            "api_slug": "customs_broker",
            "value": "Acme Brokerage"
          },
          {
            "api_slug": "seal_number",
            "value": "SEAL-0001",
            "number": ""
          }
        ]
      },
      "ref_numbers": [
        "PO12345",
        "HBL12345",
        "CUSREF1234"
      ],
      "shipment_tags": [
        "camembert"
      ],
      "scac": "MSCU"
    },
    "relationships": {
      "customer": {
        "data": {
          "id": "f7cb530a-9e60-412c-a5bc-205a2f34ba54",
          "type": "party"
        }
      }
    },
    "type": "tracking_request"
  }
}
'

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

{
  "errors": [
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/scac"
      },
      "title": "Unprocessable Entity",
      "detail": "Scac can't be blank",
      "code": "blank"
    },
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/scac"
      },
      "title": "Unprocessable Entity",
      "detail": "Scac 'XXXX' is not recognized",
      "code": "blank"
    },
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/scac"
      },
      "title": "Unprocessable Entity",
      "detail": "Scac 'UALC' is not supported. We do not currently integrate with Universal Africa Lines",
      "code": "blank"
    },
    {
      "status": "422",
      "source": {
        "pointer": "/data/attributes/request_number"
      },
      "title": "Unprocessable Entity",
      "detail": "Request number can't be blank",
      "code": "blank"
    }
  ]
}

{
  "errors": [
    {
      "status": "429",
      "title": "Too Many Requests",
      "detail": "You've hit the create tracking requests limit. Please try again in a minute."
    }
  ]
}

Don’t know the SCAC? Set auto_detect_vocc_scac to true and omit scac, and Terminal49 will infer the carrier SCAC for you. Detection runs asynchronously: the request is created immediately with status: "pending" and scac: null, then resolves to created (with the detected scac populated) or failed (failed_reason: "scac_auto_detect_failed") — poll the tracking request or use webhooks to observe the outcome. Use Auto-Detect Carrier first when your workflow needs to preview or confirm carrier candidates before submitting.

This endpoint has its own rate-limit bucket: 100 tracking requests per minute per API key/account.

Setting custom field values before the shipment exists

Use initial_custom_fields to stage custom field values at creation time, before the shipment and containers exist. Terminal49 applies shipment entries to the shipment and containers entries to their containers once the tracking request resolves. Each api_slug must match an existing custom field definition on your account — a Shipment-scoped definition for shipment entries, a Container-scoped definition for containers entries. Container entries without a number — or with number set to an empty string — are applied to every container on the shipment; include a non-empty number to target one specific container.

{
  "data": {
    "type": "tracking_request",
    "attributes": {
      "request_number": "MEDUAI047070",
      "request_type": "bill_of_lading",
      "scac": "MEDU",
      "initial_custom_fields": {
        "shipment": [
          { "api_slug": "booking_reference", "value": "BOOK-2026-001" }
        ],
        "containers": [
          { "api_slug": "po_number", "value": "PO-123", "number": "MSCU1234567" },
          { "api_slug": "po_number", "value": "PO-999", "number": "TCLU7654321" },
          { "api_slug": "customs_broker", "value": "Acme Brokerage" },
          { "api_slug": "seal_number", "value": "SEAL-0001", "number": "" }
        ]
      }
    }
  }
}

In this example, booking_reference is set on the shipment; po_number is set per container by number; and customs_broker and seal_number — which omit number or pass an empty string — are applied to every container on the shipment.

Authorizations

Authorization

string

header

required

Use a Terminal49 API key in the Authorization header with the Token prefix.

Authorization: Token YOUR_API_KEY

Body

application/json

Create a shipment tracking request

data

object

Show child attributes

Response

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

List tracking requests

Get a tracking request

⌘I

Tracking Requests

Shipments

Containers

Documents

Email Submissions

Document Schemas

Document Representations

Search

Webhooks

Webhook Notifications

Custom Field Definitions

Custom Field Options

Custom Fields

Shipping Lines

Metro Areas

Ports

Vessels

Terminals

Parties

Setting custom field values before the shipment exists

Authorizations

Body

Response

​Setting custom field values before the shipment exists

Authorizations

Body

Response

Setting custom field values before the shipment exists