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 parcels, such as Shipment in transit to carrier or Departed from shipping partner facility. You can add multiple events to multiple parcels in a single API request. You can add events according to a parcel ID, such as the tracking number, or according to a container ID, which adds the events to all the parcels in the container. The added events are included as part of the tracking information that clients retrieve through the Track a Package API and the Pitney Bowes tracking page.

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 parcels or containers in a single request.

  2. You can add up to 25 events for each shipment in a single request.

  3. You can select from the event codes listed in the Tracking Events section.

  4. The API records each event in local time with a UTC offset.

  5. 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

  • 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 ID used to identify the parcels for which to add events. Possible values:

  • package: A parcel is identified by a package ID, such as a tracking number or UPID.

  • container: A parcel is identified by its container ID. The event applies to all the parcels in the container.

    referenceSubType

String

An additional optional reference. Possible values are:

  • Courier

  • ContainerCreate

  • ContainerReceipt

  • Internal

  • USPS

    scac

String

The Standard Carrier Alpha Code (SCAC) used by the carrier.

    containerType

String

If referenceType is set to container, you can use this field to identify the type of container. Possible values are:

  • PostalSack

  • Courier Sack

  • Postal Tote

  • Letter Tray

  • Container

  • Crate

  • Skid

  • Pallet

  • Carton

  • Gaylord

    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 code for the tracking event. This must be a two- or three-letter code from the Tracking Events table.

        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

        eventLocationName

String

A description of the location, such as warehouse, depot, or airport.

        eventAddress1

String

Line 1 of the address.

        eventAddress2

String

Line 2 of the address.

        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


CUC

Customs Cleared

CUR

Customs Receipt

DCC

Delay in Custom Clearance

DLD

Delivered

DPB

Dropped off at PB facility

ERC

Exception - Rejected by Customs

HFI

Held for Inspection

LPF

Departed from shipping partner facility

PCB

Picked up from Customs Broker

RFI

Released from Inspection

TRC

Shipment in transit to carrier

TRP

In transit to PB

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 Requests

See the following examples:

Sample Request to Add Tracking Events for Packages

Sample Request to Add Tracking Events for Packages
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-86753",
        "events": [ {
            "eventCode": "DPB",
            "carrierEventCode": "DOAC",
            "eventDate": "2021-04-18",
            "eventTime": "12:48:10",
            "eventTimeOffset": "-06:00",
            "eventCity": "Decatur",
            "eventStateOrProvince": "IL",
            "postalCode": "62521",
            "country": "US"
        }, { ... } ]
    },{
        "referenceType": "package",
        "referenceValue": "3Z30-89642",
        "events": [ {
            "eventCode": "DPB",
            "carrierEventCode": "DOAC",
            "eventDate": "2021-04-18",
            "eventTime": "12:50:00",
            "eventTimeOffset": "-06:00",
            "eventCity": "Decatur",
            "eventStateOrProvince": "IL",
            "postalCode": "62521",
            "country": "US"
        }, { ... } ]
    }, { ... } ]
}'
Sample Response
{ "status": "Success" }

Sample Request to Add Tracking Events for Containers

Sample Request to Add Tracking Events for Containers
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": "container",
        "referenceSubType": "Courier",
        "scac": "DYXE",
        "containerType": "Pallet",
        "referenceValue": "42080792748455143776821",
        "events": [ {
            "eventCode": "LPF",
            "carrierEventCode": "SPARR",
            "eventDate": "2021-07-28",
            "eventTime": "12:10:00",
            "eventTimeOffset": "-06:00",
            "eventLocationName": "Airport",
            "eventAddress1": "708 S Airport Rd",
            "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.