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 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 add event listed on the Standardized Tracking Event Code List page on the PB BOXdocs website.

    The Tracking Events section below on this page provides a subset of the events listed on Standardized Tracking Event Code List.

  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

  • PBCS: PB Standard

  • PBI: CBDS

references

Array(References Object)

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

References Object (Request Only)

The references array takes the references object.

Name

Data Type

Description

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(Events Object)

Required. The events that have occurred for the shipment. Each object in this array adds a different event into the shipment’s tracking information.

Events Object (Request Only)

The references.events array takes the events object.

Name

Data Type

Description

eventCode

String

Required. The code for the tracking event. This is a two- or three-character code from the Standardized Tracking Event Code List on the PB BOXdocs website. See also the Tracking Events section below on this page.

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.

Response Element

Name

Data Type

Description

status

String

A successful response returns this field with the following value: Success

Tracking Events

You can add any of the events listed on the Standardized Tracking Event Code List page on the PB BOXdocs website. Enter the event’s code as listed in the page’s STANDARDIZED EVENT CODE column.

For example, to add the “Arrived at Carrier Facility” event, enter the code ACF in the references.events.eventCode field.

The following table shows a subset of the events listed on the Standardized Tracking Event Code List page:

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

PRA

PUDO Return Accepted

PRP

PUDO Return Pickup

RFI

Released from Inspection

TRC

Shipment in transit to carrier

TRP

In transit to PB

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" \
-d '
{
    "carrier": "PBCS",
    "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": "PBCS",
    "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 error codes returned by the Ecommerce APIs, please see Error Codes.