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 Support on the Contact Us page.

Considerations¶

You can add events for up to 250 parcels or containers in a single request.
You can add up to 25 events for each shipment in a single request.
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.
The API records each event in local time with a UTC offset.
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 Containers

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¶

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.