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 Support at ClientSupportTechServices@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 URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v2/track/events
Production: https://shipping-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 values:

  • USPS: PB Expedited, PB Presort, PMOD

  • IMB: Services that print an IMb label

  • PBS: PB Standard (formerly Newgistics)

  • PBI: CBDS

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 tables show the tracking events you can add to shipments:

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

PickUp DropOff (PUDO) Locations Only:

Event Code

Event


61

RECEIVED BY AGENT

62

RECIPIENT NOTIFIED BY AGENT

63

DELIVERED TO RECIPIENT BY AGENT

64

UNDELIVERABLE TO RECIPIENT BY AGENT

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": "PBS",
    "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

This API uses error codes 1000001 - 1000005.

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