Add Tracking Events

HTTP Request

POST /v2/track/events

Summary

Use this operation to provide an interface for shippers and parcel handlers to inject tracking events for shipments, such as Shipment in transit to carrier, Customs Cleared, or Departed from shipping partner facility. You can add multiple events to multiple shipments in a single API request. The added events are included as part of the tracking information that clients can retrieve through the Track a Package API and the Pitney Bowes tracking page. By adding events, you can provide an end-to-end view of a shipment’s journey at any point of time.

Prerequisite

To use this API, your developer account must be enabled to add tracking events. To enable this service, please contact Client Services Tech Support at ClientServicesTechSupport@pb.com.

Considerations

  1. You can add events for up to 250 shipments in a single request.
  2. Add shipments by specifying a shipment reference type and a corresponding value. For example, you can specify the package reference type and the shipment’s package tracking number.
  3. You can add up to 25 events for each shipment in a single request.
  4. You can select from the event codes listed in the Tracking Events section.
  5. The API records each event in local time with a UTC offset.
  6. You can add events for both domestic and international locations.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v2/track/events
Production: https://api.pitneybowes.com/shippingservices/v2/track/events

Request Header

Name
Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type Required. The media type of the request entity. Set this to application/json.

Request Elements

Name Data Type Description
carrier String

Required. The service for which the tracking event applies. Possible value:

references Array Required. The shipments for which to add events. Each object in this array identifies a shipment.
    referenceType String

Required. The type of reference that is used to identify shipments.

The current possible value is package, which indicates that shipments are identified by a package ID, such as a tracking number or UPID.

    referenceValue String

Required. Identifies the shipment. Enter the shipment’s value for the reference type specified in the referenceType field.

For example, if referenceType is set to package, enter the shipment’s package ID, such as the tracking number or UPID.

    events Array Required. The events that have occurred for the shipment. Each object in this array adds a different event into the shipment’s tracking information.
        eventCode String Required. The tracking event. This must be the two- or three-letter code for the event from the following table: Tracking Events
        carrierEventCode String The event code in the submitter’s system.
        eventDate String Required. The local date when the event took place, specified in the following format: YYYY-MM-DD
        eventTime String Required. The local time when the event took place, specified in the following format: HH:MM:SS
        eventTimeOffset String

Required. The UTC offset between the local time of the event and the time in UTC/GMT. Specify the offset as hours and minutes in the following format: ±[hh]:[mm]

For example, for a location six hours behind UTC, specify: -06:00

        eventCity String The city or town where the event took place.
        eventStateOrProvince String The state or province where the event took place.
        postalCode String The postal or ZIP code where the event took place.
        country String Required. The ISO country code of the country where the event took place.

Tracking Events

The following tracking events can be added to a shipment:

Event Code Event
CUR Customs Receipt
CUC Customs Cleared
DLD Delivered
LPF Departed from shipping partner facility
HFI Held for Inspection
RFI Released from Inspection
DCC Delay in Custom Clearance
ERC Exception - Rejected by Customs
TRC Shipment in transit to carrier
TRP In transit to PB
PCB Picked up from Customs Broker
DPB Dropped off at PB facility

Response Element

Name Data Type Description
status String A successful response returns this field with the following value: Success

Sample Request

curl -X POST .../v2/track/events \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "carrier": "NEWGISTICS",
    "references": [ {
        "referenceType": "package",
        "referenceValue": "1Z00",
        "events": [ {
            "eventCode": "DPB",
            "carrierEventCode": "DOAC",
            "eventDate": "2020-04-18",
            "eventTime": "12:48:10",
            "eventTimeOffset": "-06:00",
            "eventCity": "Decatur",
            "eventStateOrProvince": "IL",
            "postalCode": "62521",
            "country": "US"
        }, ...
        { ... } ]
    },{
        "referenceType": "package",
        "referenceValue": "3Z30",
        "events": [ {
            "eventCode": "DPB",
            "carrierEventCode": "DOAC",
            "eventDate": "2020-04-18",
            "eventTime": "12:50:00",
            "eventTimeOffset": "-06:00",
            "eventCity": "Decatur",
            "eventStateOrProvince": "IL",
            "postalCode": "62521",
            "country": "US"
        }, ...
        { ... } ]
    }, ...
    { ... } ]
}'

Sample Response

{ "status": "Success" }

Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.