Carrier Tracking Search API Details

Overview

Use the Shipium Carrier Tracking Search API to get tracking information about the status of single or multiple packages.

You can search in different ways:

  • Search by a carrier's tracking ID (carrierId and carrierTrackingId)
  • Search by Shipium's tracking ID (shipiumTrackingId)
  • Bulk searches

In the trackingSearchRequests and shipiumTrackingId arrays, you can provide up to 100 trackings at a time.

Search by carrierId and carrierTrackingId

This example shows the cURL request for bulk searching by a carrier's tracking ID:

curl --request POST 
  --url <<api_url>>/api/v1/tracking/bulkCarrierTrackingSearch 
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 
  --data'{
  "trackingSearchRequests": [
    {
      "carrierId": "string",
      "carrierTrackingId": "string"
    }
  ]
}'

This example shows the cURL request by an individual carrier's ID and tracking ID:

curl --request GET 
  --url <<api_url>>/api/v1/tracking/carrier/{carrierId}/{carrierTrackingId}
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 

Search by shipiumTrackingId

Request:

This example shows the cURL request bulk search of Shipium's tracking IDs:

curl --request POST 
  --url <<api_url>>/api/v1/tracking/bulkTrackingSearch 
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 
  --data '{
  "shipiumTrackingIds": [
    "string"
  ]
}'

This example shows the cURL request by an individual Shipium tracking ID:

curl --request GET 
  --url <<api_url>>/api/v1/tracking/7df8264e-6b4a-4af0-8d3f-f5246f3075e2?excludeEvents=true\
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 

Example response:

This example shows the parameters returned:

{
  "trackings": [
    {
      "carrierEstimatedDeliveryDate": "2022-06-07T21:02:33.607Z", // (This date will have the time zone offset of the delivery address)
      "carrierId": "string",
      "carrierServiceMethodId": "string",
      "carrierTrackingId": "string",
      "deliveredAtDateTime": "2022-06-07T21:02:33.607Z", 
      "shipiumTrackingId": "string",
      "shipmentStatus": "Delivered", //other statuses -> (Label Printed, In Transit, Out For Delivery, Delivered, Exception)
      "shippedDateTime": "2022-06-07T21:02:33.607Z",
      "trackingEvents": [
        {
          "city": "string",
          "country": "string",
          "carrierDescription": "string", //"Human readable shipment status message as reported by the carrier. "
          "eventDate": "2022-06-07T21:02:33.607Z",
          "postalCode": "string",
          "region": "string",
          "shipmentStatus": "Delivered", // other statuses -> (Label Printed, In Transit, Out For Delivery, Delivered, Exception)
        }
      ]
    }
  ]
}

Search by Shipium Tracking Id

Request:

curl --request GET 
  --url <<api_url>>/api/v1/tracking/7df8264e-6b4a-4af0-8d3f-f5246f3075e2
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 

Response:

{

   "shipiumTrackingId": "7df8264e-6b4a-4af0-8d3f-f5246f3075e2",
   "carrierId": "fedex",
   "carrierTrackingId": "274204633522",
   "carrierServiceMethodId": "fedex-2day-service-method",
   "shipmentStatus": "Delivered",
   "shippedDateTime": "2022-06-13T16:30:00Z",
   "deliveredAtDateTime": "2022-06-15T11:00:00-04:00",
   "carrierEstimatedDeliveryDate": null,
   "trackingEvents": [
       {
           "carrierDescription": "Delivered",
           "shipmentStatus": "Delivered",
           "eventDate": "2022-06-15T15:00:00Z",
           "postalCode": "44102",
           "country": "US",
           "city": "CLEVELAND",
           "region": "OH"
       },
       {
           "carrierDescription": "On FedEx vehicle for delivery",
           "shipmentStatus": "Out For Delivery",
           "eventDate": "2022-06-15T11:20:00Z",
           "postalCode": "44130",
           "country": "US",
           "city": "MIDDLEBURG HEIGHTS",
           "region": "OH"
       },
       {
           "carrierDescription": "At local FedEx facility",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-15T11:17:00Z",
           "postalCode": "44130",
           "country": "US",
           "city": "MIDDLEBURG HEIGHTS",
           "region": "OH"
       },
       {
           "carrierDescription": "At destination sort facility",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-15T08:56:00Z",
           "postalCode": "44135",
           "country": "US",
           "city": "CLEVELAND",
           "region": "OH"
       },
       {
           "carrierDescription": "Departed FedEx hub",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-15T00:17:00Z",
           "postalCode": "27410",
           "country": "US",
           "city": "GREENSBORO",
           "region": "NC"
       },
       {
           "carrierDescription": "Left FedEx origin facility",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-14T01:50:00Z",
           "postalCode": "75038",
           "country": "US",
           "city": "IRVING",
           "region": "TX"
       },
       {
           "carrierDescription": "Shipment arriving On-Time",
           "shipmentStatus": "Label Printed",
           "eventDate": "2022-06-13T18:08:00Z",
           "postalCode": "75038",
           "country": "US",
           "city": "IRVING",
           "region": "TX"
       },
       {
           "carrierDescription": "Picked up",
           "shipmentStatus": "In Transit",
           "eventDate": "2022-06-13T16:30:00Z",
           "postalCode": "75038",
           "country": "US",
           "city": "IRVING",
           "region": "TX"
       },
       {
           "carrierDescription": "Shipment information sent to FedEx",
           "shipmentStatus": "Label Printed",
           "eventDate": "2022-06-10T23:46:35Z",
           "postalCode": null,
           "country": null,
           "city": null,
           "region": null
       }
   ]
}

Search by CarrierId and CarrierTrackingId

Request:

curl --request GET 
  --url <<api_url>>/api/v1/tracking/carrier/ups/1Z09T5T60396196113?excludeEvents=true 
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 

Response:

{
   "shipiumTrackingId": "9e2da998-6886-438e-bb3a-3240313fb3c9",
   "carrierId": "ups",
   "carrierTrackingId": "1Z09T5T60396196113",
   "carrierServiceMethodId": "ups-ground-service-method",
   "shipmentStatus": "Delivered",
   "shippedDateTime": "2022-06-07T19:02:38Z",
   "deliveredAtDateTime": "2022-06-13T16:02:42-04:00",
   "carrierEstimatedDeliveryDate": null,
   "trackingEvents": []
}

Bulk search tracking (bulkCarrierTrackingSearch)

Request:

curl --request POST 
  --url <<api_url>>/api/v1/tracking/bulkCarrierTrackingSearch 
  --header 'accept: application/json' 
  --header $AUTHSTRING \
  --header 'content-type: application/json' 
  --data '{
   "trackingSearchRequests": [
       {
           "carrierId": "airterra",
           "carrierTrackingId": "000050001000020735"
       },
       {
           "carrierId": "ups",
           "carrierTrackingId": "1Z09T5T60396196113"
       }
   ]
}
'

Response:

{
   "trackings": [
       {
           "shipiumTrackingId": "fa87b2e3-7ef9-404c-8390-d69fbe2d5dd6",
           "carrierId": "airterra",
           "carrierTrackingId": "000050001000020735",
           "carrierServiceMethodId": "airterra-groundxc-service-method",
           "shipmentStatus": "Delivered",
           "shippedDateTime": "2022-06-22T23:38:05.607631Z",
           "deliveredAtDateTime": "2022-06-28T13:33:12-07:00",
           "carrierEstimatedDeliveryDate": "2022-06-28T00:00:00-07:00",
           "trackingEvents": [
               {
                   "carrierDescription": "Your package has been delivered",
                   "shipmentStatus": "Delivered",
                   "eventDate": "2022-06-28T20:33:12Z",
                   "postalCode": "80239",
                   "country": null,
                   "city": "AURORA",
                   "region": "CO"
               },
               {
                   "carrierDescription": "Your package is out for delivery.",
                   "shipmentStatus": "Out For Delivery",
                   "eventDate": "2022-06-28T14:09:43Z",
                   "postalCode": "80239",
                   "country": null,
                   "city": "AURORA",
                   "region": "CO"
               },
               {
                   "carrierDescription": "Your package was scanned into facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-28T01:10:57Z",
                   "postalCode": "80239",
                   "country": null,
                   "city": "DENVER",
                   "region": "CO"
               },
               {
                   "carrierDescription": "Received by AirTerra",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-22T23:38:06.1879685Z",
                   "postalCode": "18202",
                   "country": null,
                   "city": "Hazleton",
                   "region": "PA"
               },
               {
                   "carrierDescription": "Received by AirTerra",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-22T23:38:05.6076314Z",
                   "postalCode": "17901",
                   "country": null,
                   "city": "POTTSVILLE",
                   "region": "PA"
               }
           ]
       },
       {
           "shipiumTrackingId": "9e2da998-6886-438e-bb3a-3240313fb3c9",
           "carrierId": "ups",
           "carrierTrackingId": "1Z09T5T60396196113",
           "carrierServiceMethodId": "ups-ground-service-method",
           "shipmentStatus": "Delivered",
           "shippedDateTime": "2022-06-07T19:02:38Z",
           "deliveredAtDateTime": "2022-06-13T16:02:42-04:00",
           "carrierEstimatedDeliveryDate": null,
           "trackingEvents": [
               {
                   "carrierDescription": "Delivered",
                   "shipmentStatus": "Delivered",
                   "eventDate": "2022-06-13T20:02:42Z",
                   "postalCode": "00766",
                   "country": "PR",
                   "city": "VILLALBA",
                   "region": null
               },
               {
                   "carrierDescription": "Departed from Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-13T14:54:00Z",
                   "postalCode": null,
                   "country": "PR",
                   "city": "Carolina",
                   "region": "PR"
               },
               {
                   "carrierDescription": "Import Scan",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-13T10:47:32Z",
                   "postalCode": null,
                   "country": "PR",
                   "city": "Carolina",
                   "region": "PR"
               },
               {
                   "carrierDescription": "Arrived at Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-13T08:14:00Z",
                   "postalCode": null,
                   "country": "PR",
                   "city": "Carolina",
                   "region": "PR"
               },
               {
                   "carrierDescription": "Departed from Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-13T05:06:00Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Jacksonville",
                   "region": "FL"
               },
               {
                   "carrierDescription": "Departed from Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-09T17:06:00Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Jacksonville",
                   "region": "FL"
               },
               {
                   "carrierDescription": "Arrived at Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-09T12:23:00Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Jacksonville",
                   "region": "FL"
               },
               {
                   "carrierDescription": "Arrived at Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-09T03:10:00Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Jacksonville",
                   "region": "FL"
               },
               {
                   "carrierDescription": "Departed from Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-08T16:10:00Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Richmond",
                   "region": "VA"
               },
               {
                   "carrierDescription": "Arrived at Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-08T12:37:00Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Richmond",
                   "region": "VA"
               },
               {
                   "carrierDescription": "Departed from Facility",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-08T08:38:00Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Harrisburg",
                   "region": "PA"
               },
               {
                   "carrierDescription": "Origin Scan",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-08T01:15:19Z",
                   "postalCode": null,
                   "country": "US",
                   "city": "Harrisburg",
                   "region": "PA"
               },
               {
                   "carrierDescription": "Shipper created a label, UPS has not received the package yet.",
                   "shipmentStatus": "In Transit",
                   "eventDate": "2022-06-07T19:02:38Z",
                   "postalCode": null,
                   "country": "US",
                   "city": null,
                   "region": null
               }
           ]
       }
   ]
}

Bulk Search tracking using Shipium Tracking IDs

Request:

curl --request POST 
  --url <<api_url>>/api/v1/tracking/bulkTrackingSearch
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 
  --data '{
   "shipiumTrackingIds": [
           "9e2da998-6886-438e-bb3a-3240313fb3c9",
           "f4c20623-0138-4a45-a29b-24c794038b21"
   ],
   "excludeEvents": true
}
'

Response:

{
   "trackings": [
       {
           "shipiumTrackingId": "f4c20623-0138-4a45-a29b-24c794038b21",
           "carrierId": "fedex",
           "carrierTrackingId": "274212993925",
           "carrierServiceMethodId": "fedex-2day-service-method",
           "shipmentStatus": "Exception",
           "shippedDateTime": "2022-06-13T16:30:00Z",
           "deliveredAtDateTime": null,
           "carrierEstimatedDeliveryDate": null,
           "trackingEvents": []
       },
       {
           "shipiumTrackingId": "9e2da998-6886-438e-bb3a-3240313fb3c9",
           "carrierId": "ups",
           "carrierTrackingId": "1Z09T5T60396196113",
           "carrierServiceMethodId": "ups-ground-service-method",
           "shipmentStatus": "Delivered",
           "shippedDateTime": "2022-06-07T19:02:38Z",
           "deliveredAtDateTime": "2022-06-13T16:02:42-04:00",
           "carrierEstimatedDeliveryDate": null,
           "trackingEvents": []
       }
   ]
}

Behaviors to Note

  • Registered trackings are considered equivalent if they were shipped less than 30 days apart
  • carrierEstimatedDeliveryDate uses the timezone zone offset of the delivery address
  • deliveredAtDateTime uses the timezone zone offset of the delivery address
  • eventDate uses UTC time
  • If we are unable to find the delivery address or timezone of the delivery address, the date/time returned is still implied at the delivery address zone. The API defaults to UTC time ('Z') as the zone offset

If you search for a tracking ID that we didn’t register

If you search for a tracking ID that we didn’t register (when calling the single GET endpoints), the API returns a 404 not found error message.

Request example:

curl --request GET 
  --url <<api_url>>/api/v1/tracking/carrier/ups/abc123 
  --header 'accept: application/json' 
  --header $AUTHSTRING 
  --header 'content-type: application/json' 

Response example for Status 404

{
   "timestamp": "2022-07-14T19:36:09.096+00:00",
   "status": 404,
   "error": "Not Found",
   "message": "404 NOT_FOUND",
   "path": "/api/v1/tracking/carrier/ups/abc123"
}

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.


Did this page help you?