Skip to main content

​
Get a tracking request

Retrieve the details of a specific tracking request by its ID. This endpoint returns the current status of the tracking request and includes the associated shipment data if the tracking request was successful.

​
Endpoint Overview

GET /tracking_requests/{id} This endpoint retrieves tracking request details and associated shipment information.

​
Request Format

​
Headers

HeaderTypeRequiredDescription
X-API-KeystringYesYour API key for authentication

​
Path Parameters

ParameterTypeRequiredDescription
idstringYesThe unique identifier of the tracking request

​
Response Format

​
Success Response (200 OK)

{
  "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": "created",
      "failed_reason": null
    },
    "relationships": {
      "tracked_object": {
        "data": {
          "id": "eb6f218a-0b4a-47f9-8ef9-759aa5e0ea83",
          "type": "shipment"
        }
      }
    },
    "links": {
      "self": "/v2/tracking_requests/ba4cb904-827f-4038-8e31-1e92b3356218"
    }
  },
  "included": [
    {
      "id": "eb6f218a-0b4a-47f9-8ef9-759aa5e0ea83",
      "type": "shipment",
      "attributes": {
        "created_at": "2020-04-04T16:13:37-07:00",
        "bill_of_lading_number": "MEDUFR030802",
        "ref_numbers": [],
        "shipping_line_scac": "MSCU",
        "shipping_line_name": "Mediterranean Shipping Company",
        "port_of_lading_locode": "FRFOS",
        "port_of_lading_name": "Fos-Sur-Mer",
        "port_of_discharge_locode": "USOAK",
        "port_of_discharge_name": "Oakland",
        "pod_vessel_name": "MSC ALGECIRAS",
        "pod_vessel_imo": "9605243",
        "pod_voyage_number": "920A",
        "destination_locode": "USOAK",
        "destination_name": "Oakland",
        "destination_timezone": "America/Los_Angeles",
        "destination_ata_at": "2019-06-21T18:46:00-07:00",
        "destination_eta_at": null,
        "pol_etd_at": null,
        "pol_atd_at": "2019-05-24T03:00:00-07:00",
        "pol_timezone": "Europe/Paris",
        "pod_eta_at": null,
        "pod_ata_at": "2019-06-21T18:46:00-07:00",
        "pod_timezone": "America/Los_Angeles"
      },
      "relationships": {
        "port_of_lading": {
          "data": {
            "id": "6d8c6c29-72a6-49ad-87b7-fd045f202212",
            "type": "port"
          }
        },
        "port_of_discharge": {
          "data": {
            "id": "42d1ba3a-f4b8-431d-a6fe-49fd748a59e7",
            "type": "port"
          }
        },
        "pod_terminal": {
          "data": null
        },
        "destination": {
          "data": {
            "id": "42d1ba3a-f4b8-431d-a6fe-49fd748a59e7",
            "type": "port"
          }
        },
        "containers": {
          "data": [
            {
              "id": "11c1fa10-52a5-48e2-82f4-5523756b3d0f",
              "type": "container"
            }
          ]
        }
      },
      "links": {
        "self": "/v2/shipments/eb6f218a-0b4a-47f9-8ef9-759aa5e0ea83"
      }
    }
  ]
}

​
Response Fields

FieldTypeDescription
data.idstringUnique identifier for the tracking request
data.typestringResource type (always “tracking_request”)
data.attributes.request_typestringType of tracking request
data.attributes.request_numberstringThe tracking number being monitored
data.attributes.shipping_line_scacstringThe SCAC code of the shipping line
data.attributes.ref_numbersarrayArray of reference numbers
data.attributes.shipment_tagsarrayArray of tags
data.attributes.created_atstringISO 8601 timestamp when created
data.attributes.updated_atstringISO 8601 timestamp when last updated
data.attributes.statusstringCurrent status (“pending”, “created”, “failed”)
data.attributes.failed_reasonstringReason for failure if failed, null otherwise
data.relationships.tracked_object.dataobjectThe tracked shipment object if successful, null otherwise
data.links.selfstringURL to retrieve this tracking request
includedarrayArray of included related resources (shipments)

​
Status Codes

CodeDescription
200Tracking request retrieved successfully
404Tracking request not found
401Authentication failed - invalid API key
429Rate limit exceeded

​
Tracking Request Statuses

The tracking request can have the following statuses:
  • pending: The tracking request has been created and the system is attempting to fetch shipment data
  • created: The tracking request was successful and a shipment object has been created
  • failed: The tracking request failed to fetch shipment data

​
Error Responses

​
Not Found Error (404)

{
  "error": {
    "code": "not_found",
    "message": "Tracking request not found",
    "type": "not_found_error"
  }
}

​
Authentication Error (401)

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}