Track a Parcel

Note

Draft content. This operation is coming soon. This page is a draft.

HTTP Request

GET /track/{trackingNumber}?carrier={carrier}

Summary

This operation retrieves tracking events for a parcel based on the parcel’s tracking number.

Prerequisites

To use this API, contact your PB implementation manager for credentials.

Request URLs

Production: https://api.tracking.pitneybowes.com/track/{trackingNumber}

Path Parameter

Name


Description

trackingNumber

Required. The tracking number provided by the carrier.

Query Parameter

Name


Description

carrier

The carrier that handled the parcel. For valid values, see Carrier IDs used by the Track API.

Request Header

Name


Description

Authorization

Required. The bearer token (Bearer <oauthToken>).

Content-Type

Required. The media type of the request entity. Set this to application/json.

x-api-key

Required. The x-api-key received from your implementation manager.

Response Elements

Name


Data Type

Description

trackingDataResponseList

Array[Tracking Data Object]

Tracking Data Object

Name


Data Type

Description

requestedIdentifier

String

The tracking number passed in the request.

clientId

trackingNumber

String

The tracking number returned by the carrier. Note that some carriers return a different value from the tracking number passed in the request.

referenceNumber

String

A merchant-specified number.

smartLabelBarcode

String

The Pitney Bowes barcode created for the parcel, if applicable.

carrier

String

The carrier that handled the parcel. For possible values, see Carrier IDs used by the Track API.

serviceName

String

The carrier’s name for the mail class.

serviceCode

String

The carrier’s code or name for the mail class.

estimatedDeliveryDate

String

The date the parcel is expected to be delivered at the destination location, specified in the YYYY-MM-DD format.

estimatedDeliveryTime

String

The local time at the destination location that the parcel is expected to be delivered, specified in the HH:MM:SS format.

estimatedDeliveryTimeOffset

String

The UTC offset between the local time of the estimated delivery and the time in UTC/GMT. The offset is specified in the ±hh:mm format.

weight

String

The parcel’s weight.

weightUOM

String

The unit of measure for weight field.

dimension

Object

The parcel’s dimensions.

dimension.length

String

The parcel’s length.

dimension.width

String

The parcel’s width.

dimension.height

String

The parcel’s height.

dimension.unitOfMeasurement

String

The unit of measure for the dimensions.

deliveryDate

String

deliveryTime

String

The date the parcel is expected to be delivered at the destination location, specified in the YYYY-MM-DD format.

deliveryTimeOffset

String

The UTC offset between the local time of the estimated delivery and the time in UTC/GMT. The offset is specified in the ±hh:mm format.

deliveryProofUrl

shipDate

shipTime

shipTimeOffset

deliveryLocation

Location Object

currentStatus

Event Object

scanDetails

Array[Event Object]

Location Object (Track API)

Name


Data Type

Description

city

String

The city the parcel was in at the time of the event.

stateOrProvince

String

The name or 2-letter code of the state or province the parcel was in at the time of the event.

country

String

The name, 2-letter code, or 3-letter code of the country the parcel was in at the time of the event.

postalCode

String

The postal code the parcel was in at the time of the event.

description

String

The event description provided by the carrier.

Event Object (Track API)

The currentStatus and scanDetails fields return the event object.

Name


Data Type

Description

eventCode

String

The event code provided by the carrier. See the carrier’s documentation. For Pitney Bowes or USPS, see Tracking Event Codes.

l1Code

String

eventDescription

String

The event description provided by the carrier. See the carrier’s documentation. For Pitney Bowes or USPS, see Tracking Event Codes.

l1Description

String

l2Description

l3Description

status

String

The parcel’s status in the PB tracking system. Possible values are:

  • Manifest

  • Acceptance

  • InTransit

  • DeliveryAttempt

  • OutForDelivery

  • Delivered

  • Exception

  • ReturnToSender

  • ReadyForPickup

  • PickupMissed

  • PickedUp

eventLocation

Location Object

eventDate

String

eventTime

String

eventTimeOffset

String

trackingUrl

String

latitude

longitude

locationUnit

visibility

String

Sample Request

curl -X GET ".../track/61290212345678987609?carrier=FedEx" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "x-api-key: <key>"

Sample Response

{
    "trackingDataResponseList": [ {
        "requestedIdentifier": "61290212345678987609",
        "clientId": null,
        "trackingNumber": "61290212345678987609",
        "referenceNumber": null,
        "smartLabelBarcode": null,
        "carrier": "FedEx",
        "serviceName": "FedEx SmartPost",
        "serviceCode": null,
        "estimatedDeliveryDate": null,
        "estimatedDeliveryTime": null,
        "estimatedDeliveryTimeOffset": null,
        "weight": "0",
        "weightUOM": "KGS",
        "dimension": {
            "length": null,
            "width": null,
            "height": null,
            "unitOfMeasurement": null
        },
        "deliveryDate": "2022-10-27",
        "deliveryTime": "20:43:00",
        "deliveryTimeOffset": "+00:00",
        "deliveryProofUrl": null,
        "shipDate": null,
        "shipTime": null,
        "shipTimeOffset": null,
        "deliveryLocation": {
            "city": "Mission Viejo",
            "stateOrProvince": "CA",
            "country": "US",
            "postalCode": "92691",
            "description": "Delivered - Left at front door. Signature Service not requested."
        },
        "currentStatus": {
            "eventCode": "DL",
            "l1Code": "DL",
            "eventDescription": "Delivered - Left at front door. Signature Service not requested.",
            "l1Description": "Delivered - Left at front door. Signature Service not requested.",
            "l2Description": null,
            "l3Description": null,
            "status": "Delivered",
            "eventLocation": {
                "city": "Mission Viejo",
                "stateOrProvince": "CA",
                "country": "US",
                "postalCode": "92691",
                "description": null
            },
            "eventDate": "2022-10-27",
            "eventTime": "20:43:00",
            "eventTimeOffset": "+00:00",
            "trackingUrl": "https://.../index.html?tracknumbers=61290212345678987609&cntry_code=us",
            "latitude": null,
            "longitude": null,
            "locationUnit": null,
            "visibility": "external"
        },
        "scanDetails": [ {
            "eventCode": "DL",
            "l1Code": "DL",
            "eventDescription": "Delivered - Left at front door. Signature Service not requested.",
            "l1Description": "Delivered - Left at front door. Signature Service not requested.",
            "l2Description": null,
            "l3Description": null,
            "status": "Delivered",
            "eventLocation": {
                "city": "Mission Viejo",
                "stateOrProvince": "CA",
                "country": "US",
                "postalCode": "92691",
                "description": null
                },
            "eventDate": "2022-10-27",
            "eventTime": "20:43:00",
            "eventTimeOffset": "+00:00",
            "trackingUrl": "https://.../index.html?tracknumbers=61290212345678987609&cntry_code=us",
            "latitude": null,
            "longitude": null,
            "locationUnit": null,
            "visibility": "external"
        },
        ...
        ],
    } ],
    "errors": []
}

Error Codes

Error Code

Description

1000001

Invalid Carrier

1000002

No Tracking data available for the referenceNumber

1000003

Invalid reference number

1000004

Invalid clientId

1000005

Internal server error

1000006

Carrier request limit reached,please try again later

1000007

Requested carrier is not responding at the moment,please try again later