Subscribe to a Tracking Number API

Note

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

HTTP Request

GET /track/{trackingNumber}?carrier={carrier}&clientId={ID}&subscribe=true

Summary

This operation subscribes a webhook to receive events for a specified tracking number. The operation subscribes to events for labels that were not purchased through Pitney Bowes. There is a charge for this service. Contact your PB implementation manager for details.

Prerequisites

To use the Subscription API, you must:

  1. Set up a webhook to receive tracking data from Pitney Bowes. See Receive Tracking Information through a Webhook.

  2. Contact your PB implementation manager for to enable this service, which is a pay service.

Request URLs

Production: https://api.tracking.pitneybowes.com/track/{trackingNumber}?carrier={carrier}&clientId={ID}&subscribe=true

Path Parameter

Name

Description

trackingNumber

Required. The tracking number provided by the carrier.

Query Parameters

Name

Description

carrier

Required. The carrier that provided the tracking number. For valid IDs, see Carrier IDs used by the Track API.

clientId

The client ID received from your Pitney Bowes implementation manager.

subscribe

Required. Set this to: true

Request Header

Name


Description

Authorization

Required. The bearer token (Bearer <oauthToken>) retrieved using the Generate an OAuth Token for the Track API API.

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[Object]

This array returns the Tracking Data Response List objects that contain the tracking events.

Tracking Data Response List Object

Name

Data Type

Description

requestedIdentifier

String

clientId

String

trackingNumber

String

The tracking number for the shipment.

referenceNumber

String

The value passed by the carrier as referenceNumber.

smartLabelBarcode

String

This field returns the null value.

carrier

String

The carrier, as identified by the carrier ID. See Carrier IDs used by the Track API.

serviceName

String

The carrier’s name for the mail class.

serviceCode

String

The carrier’s code for the mail class.

serviceDirection

estimatedDeliveryDate

String

The estimated date at the destination that the package will be delivered, specified in the YYYY-MM-DD format.

estimatedDeliveryTime

String

The estimated local time at the destination that the package will 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

Weight of the package delivered.

weightUOM

String

Unit of measure for the package’s weight.

dimension

Object

This object has the following fields:

  • length

  • width

  • height

  • unitOfMeasurement

deliveryDate

String

The date at the destination when the package was delivered, specified in the YYYY-MM-DD format.

deliveryTime

String

The local time at the destination when the package was delivered, specified in the HH:MM:SS format.

deliveryTimeOffset

String

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

deliveryProofUrl

String

The URL to access either a picture of the delivered package or a picture of the signature confirmation.

shipDate

String

The date at the origin when the package was shipped, specified in the YYYY-MM-DD format.

shipTime

String

The time at the origin when the package was shipped, specified in the hh:mm:ss format.

shipTimeOffset

String

The UTC offset between the local time for the ship time and the time in UTC/GMT. The offset is specified in the ±hh:mm format.

deliveryLocation

Object

This object has the following fields, each of which returns a String value:

  • city

  • stateOrProvince

  • country

  • postalCode

  • description

currentStatus

Object

This field returns the Event Object.

scanDetails

Array[Object]

The array returns one or more event objects.

Event Object in the Track API

The scanDetails and currentStatus fields return the event object.

Name

Data Type

Description

eventCode

String

standardizedEventCode

String

l1Code

String

The event code provided by the carrier. See the carrier’s documentation.

eventDescription

String

l1Description

String

The event description provided by the carrier. See the carrier’s documentation.

l2Description

String

An additional event description provided by the carrier, if applicable. See the carrier’s documentation.

l3Description

String

status

String

eventLocation

Object

Where the event occurred. This object has the following fields, each of which returns a String value:

  • city: The city where the event occurred.

  • stateOrProvince: The state or province where the event occurred.

  • country: The country where the event occurred.

  • postalCode: The postal code where the event occurred.

  • description

eventDate

String

The date posted by the carrier for the event. Format: YYYY-MM-DD

eventTime

String

The time posted by the carrier for the event. Format: HH:MM:SS

eventTimeOffset

String

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

trackingUrl

String

latitude

String

longitude

String

locationUnit

String

visibility

String

eventLeg

String

eventType

String

Sample Request

curl GET .../track/{trackingNumber}?carrier={carrier}&clientId={ID}&subscribe=true \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "x-api: <key>"

Sample Response

{
    "trackingDataResponseList": [ {
        "requestedIdentifier": "9400108205499957706779",
        "clientId": "74958292",
        "trackingNumber": "9400108205499957706779",
        "referenceNumber": null,
        "smartLabelBarcode": null,
        "carrier": "USPS",
        "serviceName": "First-Class Package Service",
        "serviceCode": "001",
        "serviceDirection": null,
        "estimatedDeliveryDate": null,
        "estimatedDeliveryTime": null,
        "estimatedDeliveryTimeOffset": null,
        "weight": "",
        "weightUOM": "LBS",
        "dimension": {
            "length": null,
            "width": null,
            "height": null,
            "unitOfMeasurement": null            },
        "deliveryDate": "2022-08-23",
        "deliveryTime": "09:51:00",
        "deliveryTimeOffset": "-05:00",
        "deliveryProofUrl": null,
        "shipDate": "2022-08-17",
        "shipTime": "19:06:38",
        "shipTimeOffset": "+00:00",
        "deliveryLocation": {
            "city": "ALGONQUIN",
            "stateOrProvince": "IL",
            "country": "",
            "postalCode": "60102",
            "description": "Delivered, In/At Mailbox"            },
        "currentStatus": {
            "eventCode": "01",
            "standardizedEventCode": "DLD",
            "l1Code": "DLD",
            "eventDescription": "Delivered, In/At Mailbox",
            "l1Description": "Delivered",
            "l2Description": "Delivered",
            "l3Description": "Delivered",
            "status": "Delivered",
            "eventLocation": {
                "city": "ALGONQUIN",
                "stateOrProvince": "IL",
                "country": "",
                "postalCode": "60102",
                "description": ""                },
            "eventDate": "2022-08-23",
            "eventTime": "09:51:00",
            "eventTimeOffset": "-05:00",
            "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=9400108205499957706779",
            "latitude": null,
            "longitude": null,
            "locationUnit": null,
            "visibility": "external",
            "eventLeg": "FML",
            "eventType": "FWD"            },
        "scanDetails": [ {
            "eventCode": "01",
            "standardizedEventCode": "DLD",
            "l1Code": "DLD",
            "eventDescription": "Delivered, In/At Mailbox",
            "l1Description": "Delivered",
            "l2Description": "Delivered",
            "l3Description": "Delivered",
            "status": "Delivered",
            "eventLocation": {
                "city": "ALGONQUIN",
                "stateOrProvince": "IL",
                "country": "",
                "postalCode": "60102",
                "description": ""                    },
            "eventDate": "2022-08-23",
            "eventTime": "09:51:00",
            "eventTimeOffset": "-05:00",
            "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1=9400108205499957706779",
            "latitude": null,
            "longitude": null,
            "locationUnit": null,
            "visibility": "external",
            "eventLeg": "FML",
            "eventType": "FWD"
        },
        ...
        ]
    },
    ...
    ],
    "errors": []
}