Track & Confirm API

 

USPS Web Tools™

Application Programming Interface

User Guide

Version 4.2 (04/15/2021)

 

 

 

 

 

 

United States Postal Service Logo 

 

 

 


 


Table of Contents

1.0        Introduction. 4

1.1        Before you get started: 4

1.2        Tracking Service APIs. 4

2.0        Package Track API 4

2.1        Overview. 4

2.1.1     API Signature Table. 5

2.2        Request Descriptions. 5

2.2.1     Sample Request 5

2.3        Response Descriptions. 5

2.3.1     Sample Response. 6

3.0        Package Tracking “Fields” API 6

3.1        Overview. 6

3.1.1     API Signature. 6

3.2        Request Descriptions. 7

3.2.1     Sample Request 7

3.3        Response Descriptions. 8

3.3.1     Response Descriptions Continued (Revision = 1) 10

3.3.2     Sample Response. 18

4.0        Track and Confirm by Email API 20

4.1        Overview. 20

4.1.1     API Signature. 20

4.2        Request Descriptions. 20

4.2.1     Sample Request 22

4.3        Response Descriptions. 22

4.3.1     Sample Response. 22

5.0        Proof of Delivery API 22

5.1        Overview. 22

5.1.1     API Signature. 23

5.2        Request Descriptions. 23

5.2.1     Sample Request 24

5.3        Response Descriptions. 25

5.3.1     Sample Response. 25

6.0        Return Receipt Electronic API 25

6.1        Overview. 25

6.1.1     API Signature. 25

6.2        Request Descriptions. 25

6.2.1     Sample Request 26

6.3        Response Descriptions. 27

6.3.1     Sample Response. 27

7.0        Track Proof of Delivery API 27

7.1        Overview. 27

7.1.1     API Signature. 27

7.2        Request Descriptions. 27

7.2.1     Sample Request 29

7.3        Response Descriptions. 29

7.3.1     Sample Response. 29

 


 

1.0   Introduction

This document contains a Reference Guide to the USPS Tracking/Delivery Confirmation Label APIs. See the Developers Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and troubleshooting.

Note: The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags. If the user enters more than those amounts, an error will not be generated. Web Tools will simply pass in the characters up to the maximum amount allowed and disregard the rest. This is important since the resulting value could prevent a correct response.

When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered. Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values. For instance, a line of sample code may be:

<TrackID> EJ123456780US </TrackID>

In this instance, you will replace “EJ123456780US” with the tracking ID for the package.

1.1    Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Web Tools Technical Documentation Page.

1.2    Tracking Service APIs

Four service APIs are offered in conjunction with “Revision=1” of the Package Tracking “Fields” API: Track and Confirm by Email, Proof of Delivery, Tracking Proof of Delivery, and Return Receipt Electronic. The response data from Track/Confirm Fields request determines which services are available for a tracking ID. Each request input to the Web Tools server for the tracking service APIs is limited to one tracking ID. These APIs require additional permissions from the WebTools Program Office in order to gain access. When you request access for these APIs, please identify your anticipated API volume, mailer ID, and how you will be utilizing this API. A mailer identification number (MID) is a 6 or 9-digit number assigned to a customer through the USPS Business Customer Gateway (BCG). Please refer to the following links for help:

 

2.0   Package Track API

2.1    Overview

The Track/Confirm Web Tools API provides tracking status and delivery information for USPS packages. The Track/Confirm API limits the data requested to thirty-five (35) packages per transaction.

Note: The data returned by the Package Track Web Tools API is intended for display only. The content or sequence of the String data returned by the API may change. Consequently, if you desire to apply any kind of logic against the tracking data, then you will need to use the Track/Confirm fields.

2.1.1   API Signature Table

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=TrackV2

&XML=(see below)

2.2    Request Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

TrackRequest

Required 

API=TrackV2

(Alias)

 

TrackRequest / USERID

Required 

This attribute specifies your WebTools ID. See the Developers Guide for information on obtaining your USERID

For example:

<USERID=”XXXXXXXXXX”>

String

 

TrackRequest / TrackID

Required 

Must be alphanumeric characters.

For example:  <TrackID ID="EJ123456780US">

</TrackID>

String

minOccurs="1"

TrackRequest

Required

 

(Alias)

 

2.2.1   Sample Request

Request: Package Track

<TrackRequest USERID="XXXXXXXXXXXX">

<TrackID ID="XXXXXXXXXXX1"></TrackID>

<TrackID ID="XXXXXXXXXXX2"></TrackID>

</TrackRequest>

2.3    Response Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

TrackResponse

Required 

 

(Alias)

 

TrackResponse / RequestSeqNumber

Required 

A unique identification number for a request. The same number will show in the response for this request.

String

minOccurs="1"

 

TrackResults / ID

Required

Tracking ID

String

 

TrackResponse / TrackInfo

 

 

(Group)

 

TrackResponse / TrackInfo / DeliveryNotificationDate

Required

 

String

minOccurs="0"

TrackResponse / TrackInfo / ExpectedDeliveryDate

Optional

Expected delivery date

String

minOccurs="0"

TrackResponse / TrackInfo / ExpectedDeliveryTime

Optional

Expected Delivery Time

String

minOccurs="0"

TrackResponse / TrackInfo / GuaranteedDeliveryDate

Optional

Guaranteed Delivery Date – Global Express Mail only: certain countries provide a guarantee delivery

For Example: April 15, 2020

Or

3 Business Days

String

minOccurs="0"

TrackResponse / TrackInfo / TrackSummary

Optional

Summary of the status of the shipment, ie In-Transit, Delivered, etc.

For example: February 5 7:28 pm ENROUTE 33699

String

 

TrackResponse / TrackInfo / TrackDetail

Optional

Scan statuses from points in transit.

String

minOccurs="0"

TrackResponse

Required

 

(Alias)

 

2.3.1   Sample Response

Response: Package Track

<TrackResponse>

<TrackInfo ID="XXXXXXXXXXX1">

<TrackSummary> Your item was delivered at 6:50 am on February 6 in BARTOW FL 33830.</TrackSummary>

<TrackDetail>February 6 6:49 am NOTICE LEFT BARTOW FL 33830</TrackDetail>

<TrackDetail>February 6 6:48 am ARRIVAL AT UNIT BARTOW FL 33830</TrackDetail>

<TrackDetail>February 6 3:49 am ARRIVAL AT UNIT LAKELAND FL 33805</TrackDetail>

<TrackDetail>February 5 7:28 pm ENROUTE 33699</TrackDetail>

<TrackDetail>February 5 7:18 pm ACCEPT OR PICKUP 33699</TrackDetail>

</TrackInfo>

<TrackInfo ID="XXXXXXXXXXX2">

<TrackSummary There is no record of that mail item. If it was mailed recently, It may not yet be tracked. Please try again later. </TrackSummary>

</TrackResponse>

3.0   Package Tracking “Fields” API

3.1    Overview

The Package Tracking “Fields” API is similar to the Package Track API except for the request fields, API name, and the return information. Data returned still contains the detail and summary information, but this information is broken down into fields instead of having only one line of text. Up to 10 tracking IDs may be contained in each API request to the Web Tools server.

3.1.1   API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=TrackV2

&XML=(see below)

3.2    Request Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

TrackFieldRequest

Required

API=TrackV2

(Alias)

 

TrackFieldRequest / USERID

Required

This attribute specifies your Web Tools ID. See the Developers Guide for information on obtaining your USERID.

For Example: <USERID=”XXXXXXXXXXXX”>

String

 

TrackFieldRequest / Revision

Required

This is for versioning of the API's and for triggering response tags for future versions. In this API use a value of 1 to return all available response tags and trigger new functionality.

For example:  <Revision>1</Revision>

Integer

minOccurs="0"

TrackFieldRequest / ClientIp

Optional

User IP address. Required when TrackFieldRequest[Revision='1'].

For example: <ClientIp>137.0.0.1</ClientIp>

String

minOccurs="0"

TrackFieldRequest / SourceId

Required

External integrators should pass company name.

For example: <SourceId>XYZ Corp</SourceId>

String

minOccurs="0"

Pattern="[0-9]{5}"

TrackFieldRequest / TrackID

Required

Package Tracking ID.  Must be alphanumeric characters.

For example:  <TrackID ID="EJ123456780US"></TrackID>

String

minOccurs="1"

TrackFieldRequest / TrackID / DestinationZipCode

Optional

5 digit destination zip code.

For example: <DestinationZipCode>12345</DestinationZipCode>

String

minOccurs="0"

TrackFieldRequest / TrackID / MailingDate

Optional

Mailing date of package.  Format: YYYY-MM-DD

For example: <MailingDate>2010-01-01</MailingDate>

String

minOccurs="0"

TrackFieldRequest

Required

 

(Alias)

 

3.2.1   Sample Request  

Request: Track and Confirm

<TrackFieldRequest USERID="XXXXXXXXXXXX">

<Revision>1</Revision>

<ClientIp>122.3.3</ClientIp>

<SourceId>XYZ Corp</SourceId>

<TrackID ID="XXXXXXXXXXXXXXXX"/>

</TrackFieldRequest>

 

3.3    Response Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

TrackResponse

Required

 

(Alias)

 

TrackResponse / TrackInfo

Required

 

(Group)

 

TrackResponse / TrackInfo / ID

Required

Package Tracking ID number. 

String

 

TrackResponse / TrackInfo / Guaranteed Delivery Date

Optional

Guaranteed Delivery Date – Global Express Mail only:  certain countries provide a guarantee delivery.

String

 

TrackResponse / TrackInfo / eSOFEligible

Optional

Signifies if the mail piece is eSOF eligible.

Boolean

 

TrackResponse / TrackInfo / TrackSummary

Required once

Tracking Summary Information.

(Group)

 

TrackResponse / TrackInfo / TrackSummary / EventTime

Required

The time of the event.

String

 

TrackResponse / TrackInfo / TrackSummary / EventDate

Required

The date of the event.

String

 

TrackResponse / TrackInfo / TrackSummary / Event

Required

The event type (e.g., Enroute).

String

 

TrackResponse / TrackInfo / TrackSummary / EventCity

Required

City where the event occurred.

String

 

TrackResponse / TrackInfo / TrackSummary / EventState

Required

State where the event occurred.

String

 

TrackResponse / TrackInfo / TrackSummary / EventZIPCode

Required

ZIP Code of the event.

String

 

TrackResponse / TrackInfo / TrackSummary / EventCountry

Optional

Country where the event occurred.

String

 

TrackResponse / TrackInfo / TrackSummary / FirmName

Optional

Company name if delivered to a company.

String

 

TrackResponse / TrackInfo / TrackSummary / Name

Optional

Name of the persons signing for delivery (if available).

String

 

TrackResponse / TrackInfo / TrackSummary / EventCode

Optional

The event code.

String

 

TrackResponse / TrackInfo / TrackSummary / ActionCode

Optional

The action code.

String

 

TrackResponse / TrackInfo / TrackSummary / ReasonCode

Optional

The reason code

String

 

TrackResponse / TrackInfo / TrackDetail

Required once

Tracking Detail Information. This group is repeatable.

(Group)

 

TrackResponse / TrackInfo / TrackDetail / EventTime

Required

The time of the event.

String

 

TrackResponse / TrackInfo / TrackDetail / EventDate

Required

The date of the event.

String

 

TrackResponse / TrackInfo / TrackDetail / Event

Required

The event type (e.g., Enroute).

String

 

TrackResponse / TrackInfo / TrackDetail / EventCity

Required

The city where the event occurred.

String

 

TrackResponse / TrackInfo / TrackDetail / EventState

Required

The state where the event occurred.

String

 

TrackResponse / TrackInfo / TrackDetail / EventZIPCode

Required

The ZIP Code of the event

String

 

TrackResponse / TrackInfo / TrackDetail / EventCountry

Optional

The country where the event occurred.

String

 

TrackResponse / TrackInfo / TrackDetail / FirmName

Optional

The company name if delivered to a company.

String

 

TrackResponse / TrackInfo / TrackDetail / Name

Optional

The name of the persons signing for delivery (if available).

String

 

TrackResponse / TrackInfo / TrackDetail / AuthorizedAgent

Optional

True/False field indicating the person signing as an Authorized Agent.

String

Enumeration=

·         True

·         False

TrackResponse / TrackInfo / TrackDetail / EventCode

Optional

The event code

String

 

TrackResponse / TrackInfo / TrackDetail / ActionCode

Optional

The action code

String

 

TrackResponse / TrackInfo / TrackDetail / ReasonCode

Optional

The reason code

String

 

TrackResponse

Required

 

(Alias)

 

 

3.3.1   Response Descriptions Continued (Revision = 1)

Tag Name

Occurs

Descriptions

Type

Validation

TrackResults/ RequestSeqNumber

Required max 1

A unique identification number for a request. The same number that was provided in the request.

For example: 122

Integer

 

TrackResults / TrackInfo ID

Required max 10

The tracking number ID submitted through the request

For example: EA123456795US

12887393000019

String

 

TrackResults / TrackInfo / AdditionalInfo

Optional

Additional package information

String

 

TrackResults / TrackInfo / ADPScripting

Optional

Additional ADP scripting specific to the ADP Type code

String

 

TrackResults / TrackInfo / ArchiveRestoreInfo

Optional

Information regarding availability of Restore service function 

For example Yes

String

 

TrackResults / TrackInfo / AssociatedLabel

Optional

Additional Label on the mail piece

For example: EA123456785US

This is not currently populated.

String

 

TrackResults / TrackInfo / CarrierRelease

Optional

True/False field indicating the item qualifies for the customer to electronically authorize shipment release.

String

 

TrackResults / TrackInfo / Class

Optional

Mail Class of the mail piece (human readable).  This will also include the service standard message if it exists. 

No Default of False.

String

Enumerations=

·         True

·         False

TrackResults / TrackInfo / ClassofMailCode

Optional

Mail Class of the mail piece (code).  For example:EX, PM, CP, IP

String

 

TrackResults / TrackInfo / DestinationCity

Optional

The destination city. For example: Rochester

String

 

TrackResults / TrackInfo / DestinationCountryCode

Optional

The destination country code.  For example:MX, CA

String

 

TrackResults / TrackInfo / DestinationState

Optional

The destination State. For example: NY

String

 

TrackResults / TrackInfo / DestinationZip

Optional

The destination ZIP code.  For example:20024

String

 

TrackResults / TrackInfo / EditedLabelID

Optional

Edited Label ID or Full Label ID. Used only when Source ID is IVR For example:EA123456795US

String

Enumerations=

·         True

·         False

TrackResults / TrackInfo / EmailEnabled

Optional

Signifies if USPS Tracking by Email service is enabled.

Boolean

 

TrackResults / TrackInfo / EndOfDay

Optional,  used only when end of day condition is met

Populated with the end of day time provided by TRP when TRP API indicates the window is “End of Day” or when the piece is eligible for the PTR default end of day.

For example: by 5:00pm

Note: an end of day scenario occurs when the TRP API response indicates a 0 length window.

String

 

TrackResults / TrackInfo / eSOFEligible

Optional

Signifies if the mailpiece is eSOF eligibile.

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / ExpectedDeliveryDate

Optional

Expected delivery date. For example:December 31, 2013

String

 

TrackResults / TrackInfo / ExpectedDeliveryTime

Optional

Expected Delivery Time. For example: 3:00 PM

String

 

TrackResults / TrackInfo / ExpectedDeliveryType

Optional

Populates “Expected Delivery by” if there is an EDD. For example: Expected Delivery by

String

 

TrackResults / TrackInfo / GuaranteedDeliveryDate

Optional

Guaranteed Delivery Date – Global Express Mail only: certain countries provide a guarantee delivery.

For example: April 15, 2011 or 3 Business Days

String

 

TrackResults / TrackInfo / GuaranteedDeliveryTime

Optional

Guaranteed Delivery Time provided for Priority Mail Express. For example: 3:00 PM

String

 

TrackResults / TrackInfo / GuaranteedDeliveryType

Optional

Populates “Scheduled Delivery by” if there is a GDD. For example: Scheduled Delivery by

String

 

TrackResults / TrackInfo / GuaranteedDetails

Optional

Special messaging related to the guarantee. For example: “Loss Only Guarantee”

String

 

TrackResults / TrackInfo / ItemShape

Optional

Indicates the shape of the item.

String

Enumerations=

·         Letter

·         Flat

·         Parcel

·         Unknown

TrackResults / TrackInfo / KahalaIndicator

Optional

 

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / MailTypeCode

Optional

 

String

 

TrackResults / TrackInfo /  MPDATE

Optional

Internal date stamp.

String

 

TrackResults / TrackInfo / MPSUFFIX

Optional

Internal suffix.

2010-03-30 19:30:48.224343

Integer

 

TrackResults / TrackInfo / OnTime

Optional

Field indicating if the item will be delivered on time as specified in the Expected or Guaranteed delivery date.

String

Enumerations=

·         True

·         False

TrackResults / TrackInfo /  OriginCity

Optional

The origin city.

String

 

TrackResults / TrackInfo / OriginCountryCode

Optional

The origin country code.

String

 

TrackResults / TrackInfo / OriginState

Optional

The origin state.

String

 

TrackResults / TrackInfo /  OriginZip

Optional

The origin ZIP code.

String

 

TrackResults / TrackInfo / PodEnabled

Optional

Signifies if Proof of Delivery service is enabled.

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / PredictedDeliveryDate

Optional

Predicted delivery date.  December 30, 2013

String

 

TrackResults / TrackInfo / PredictedDeliveryTime

Optional

Predicted Delivery Time 3:00 PM or blank.

String

 

TrackResults / TrackInfo / PredictedDeliveryType

Optional

Populates “Expected Delivery ‘by or on’”, if the source of the PDD is TRP API.

Populates “Expected Delivery on” if the source of the PDD is a PTR calculated date.

For example: Expected Delivery by or Expected Delivery on

String

 

TrackResults / TrackInfoPredictedDeliverySource

Optional

States which system provided the Predicted Delivery prediction.

TRP, AA

String

 

TrackResults / TrackInfo / PDWStart

Optional

Predicted Delivery Window start time in am/pm format.

In an EndOfDay scenario, the PDWStart tag is null.

11:00am

For example: (null)

String

 

TrackResults / TrackInfo / PDWEnd

Optional

Predicted Delivery Window end time in am/pm format.

In an EndOfDay scenario, the PDWEnd tag is null.

1:00pm

For example: (null)

String

 

TrackResults / TrackInfo / PurgeByDate

Optional

Contains the Purge By Date of the mail piece.

Example: December 31, 2024

String

 

TrackResults / TrackInfo / RelatedRRID

Optional

The related label ID between a tracking barcode, the core product, and a PS3811, Green Card Return Reciept. This field can contain either the core product label ID or the Green Card label ID. There is only a one to one relationship.

Core Product  ID: EA123456795US

Or Green Card ID;

9590940112345671234567

String

 

TrackResults / TrackInfo / RedeliveryEnabled

Optional

Field indicating if the item qualifies for redelivery.

String

Enumerations=

·         True

·         False

TrackResults / TrackInfo / RestoreEnabled

Optional

Signifies if Restore tracking information service is enabled

Values:

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / ReturnDateNotice

Optional

Field indicating the date the item will be Returned to Sender.

String

 

TrackResults / TrackInfo / PodEnabled

Optional

Signifies if Proof of Delivery service is enabled

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / TpodEnabled

Optional

Signifies if Tracking Proof of Delivery service is enabled

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / RRAMenabled

Optional

Signifies if RRAM service is enabled

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / RreEnabled

Optional

Signifies if Return Receipt Electronic service is enabled

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / Service

Optional
unbounded

Additional services purchased

String

 

TrackResults / TrackInfo / ServiceTypeCode

Optional
max 1

Service Type Code of the mail piece

M, AD, VI, 03, 70, 716

String

 

TrackResults / TrackInfo / Status

Optional

For example: Delivered

String

 

TrackResults / TrackInfo / StatusCategory

Optional

For example: In Transit

String

 

TrackResults / TrackInfo / StatusSummary

Optional

Status summary

For example: Your item was delivered at 12:55 pm on April 05, 2010 in FALMOUTH, MA 02540

String

 

TrackResults / TrackInfo / TABLECODE

Optional

Internal description of mail piece as it relates to PTR (live, history, or archived piece) T, H, A (CMC830 V3 – T is the only value defined)

String

 

TrackResults / TrackInfo / ValueofArticle <placeholder>

Optional

Value of Article for when the Source ID is PIN

String

 

TrackResults / TrackInfo / TrackSummary

Optional
max 1

Tracking Summary Information.

(Group)

 

TrackResults / TrackInfo / TrackSummary / EventTime

Optional

The time of the event.

String

 

TrackResults / TrackInfo / TrackSummary / EventDate

Optional

The date of the event.

String

 

TrackResults / TrackInfo / TrackSummary / Event

Optional

The event type

String

 

TrackResults / TrackInfo / TrackSummary / EventCity

Optional

The city where the event occurred.

String

 

TrackResults / TrackInfo / TrackSummary / EventState

Optional

The state where the event occurred.

String

 

TrackResults / TrackInfo / TrackSummary / EventZIPCode

Optional

The ZIP Code of the event.

String

 

TrackResults / TrackInfo / TrackSummary / EventCountry

Optional

The country where the event occurred.

String

 

TrackResults / TrackInfo / TrackSummary / FirmName

Optional

The company name if delivered to a company.

String

 

TrackResults / TrackInfo / TrackSummary / Name

Optional

The first initial and last name of the person signing for delivery (if available).

String

 

TrackResults / TrackInfo / TrackSummary / EventCode

Optional

 

String

 

TrackResults / TrackInfo / TrackSummary / ActionCode

Optional
max 1

 

String

 

TrackResults / TrackInfo / TrackSummary / ReasonCode

Optional

 

String

 

TrackResults / TrackInfo / TrackSummary / GeoCertified

Optional

Only eligible to display with delivery (01) events.

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / TrackDetail

Optional
max 99

Tracking Detail Information. This group is repeatable.

(Group)

 

TrackResults / TrackInfo / TrackDetail / DeliveryAttributeCode

Optional

Used to provide additional information regarding an event posted to a mail piece.

String

Enumerations=

·         32

TrackResults / TrackInfo / TrackDetail / EventTime

Optional

The time of the event.

String

 

TrackResults / TrackInfo / TrackDetail / EventDate

Optional

The date of the event.

String

 

TrackResults / TrackInfo / TrackDetail / Event

Optional

The event type.

String

 

TrackResults / TrackInfo / TrackDetail / EventCity

Optional

The city where the event occurred.

String

 

TrackResults / TrackInfo / TrackDetail / EventState

Optional

The state where the event occurred.

String

 

TrackResults / TrackInfo / TrackDetail / EventStatusCategory

Optional

The status of a posted event on a mail piece.

String

 

TrackResults / TrackInfo / TrackDetail / EventPartner

Optional

Stores the name of the shipping partner associated to a posted shipping partner event (80,81,82).

String

 

TrackResults / TrackInfo / TrackDetail / EventZIPCode

Optional

The ZIP Code of the event.

String

 

TrackResults / TrackInfo / TrackDetail / EventCountry

Optional

The country where the event occurred.

String

 

TrackResults / TrackInfo / TrackDetail / FirmName

Optional

The company name if delivered to a company.

String

 

TrackResults / TrackDetail / Name

Optional

The name of the persons signing for delivery (if available).

String

 

TrackResults / TrackInfo / TrackDetail / AuthorizedAgent

Optional

True/False field indicating the person signing as an Authorized Agent.

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / TrackDetail / EventCode

Optional

 

String

 

TrackResults / TrackInfo / TrackDetail / ActionCode

Optional
max 1

 

String

 

TrackResults / TrackInfo / TrackDetail / ReasonCode

Optional

 

String

 

TrackResults / TrackInfo / TrackDetail / GeoCertified

Optional

Only eligible to display with delivery (01) events.

Boolean

Enumerations=

·         True

·         False

TrackResults / TrackInfo / Error

Optional

 

(Group)

 

TrackResults / TrackInfo / Error / Number

 

Optional

Assigned number for the type of error message.

String

 

TrackResults / TrackInfo / Error / ErrorDescription

Optional

Descriptions of error message.

Duplicate or 4 items were also tied to your 3849 ID but exceeded the maximum number of tracking number inquiries supported on this site.

This 3849 ID was used on a large volume shipment and cannot be used for tracking on this site.

String

 

TrackResults / TrackInfo / Error

Optional

 

(Group)

 

TrackResponse

Required

 

(Alias)

 

3.3.2   Sample Response

Response: Package Tracking “Fields”

<TrackResponse>

<TrackInfo ID="XXXXXXXXXXXXXXXXXX">

<TrackSummary>

<EventTime>10:45 pm</EventTime>

<EventDate>January 6, 2016</EventDate>

<Event>Arrived at USPS Facility</Event>

<EventCity>COLUMBUS</EventCity>

<EventState>OH</EventState>

<EventZIPCode>43218</EventZIPCode>

<EventCountry></EventCountry>

<FirmName></FirmName>

<Name></Name>

<AuthorizedAgent>false</AuthorizedAgent>

</TrackSummary>

<TrackDetail>

<EventTime>9:10 am</EventTime>

<EventDate>January 6, 2016</EventDate>

<Event>Acceptance</Event>

<EventCity>LAKE CHARLES</EventCity>

<EventState>IL</EventState>

<EventZIPCode>12345</EventZIPCode>

<EventCountry></EventCountry>

<FirmName></FirmName>

<Name></Name>

<AuthorizedAgent>false</AuthorizedAgent>

</TrackDetail>

</TrackInfo>

</TrackResponse>

Response (Revision = 1): Package Tracking “Fields”

<TrackResponse>

<TrackInfo ID="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX">

<CarrierRelease>false</CarrierRelease>

<Class>Priority Mail Express&lt;SUP&gt;&amp;reg;&lt;/SUP&gt;</Class>

<ClassOfMailCode>EX</ClassOfMailCode>

<DestinationCity>BIRMINGHAM</DestinationCity>

<DestinationState>AL</DestinationState>

<DestinationZip>35212</DestinationZip>

<EmailEnabled>true</EmailEnabled>

<KahalaIndicator>false</KahalaIndicator>

<MailTypeCode>DM</MailTypeCode>

<MPDATE>2019-08-21 10:44:08.000000</MPDATE>

<MPSUFFIX>999999999</MPSUFFIX>

<PodEnabled>true</PodEnabled>

<TPodEnabled>false</TPodEnabled>

<RedeliveryEnabled>false</RedeliveryEnabled>

<RestoreEnabled>false</RestoreEnabled>

<RramEnabled>false</RramEnabled>

<RreEnabled>false</RreEnabled>

<Service>PO to Addressee</Service>

<Service>Up to $100 insurance included</Service>

<ServiceTypeCode>701</ServiceTypeCode>

<Status>Delivered</Status>

<StatusCategory>Deliverery Attempt, action needed</StatusCategory>

<StatusSummary>Your item was delivered at 7:30 am on August 21, 2019 in BIRMINGHAM, AL 35212.</StatusSummary>

<TABLECODE>T</TABLECODE>

<TrackSummary>

<EventTime>7:30 am</EventTime>

<EventDate>August 21, 2019</EventDate>

<Event>CMC1496 SIT testing - Delivered</Event>

<EventCity>BIRMINGHAM</EventCity>

<EventState>AL</EventState>

<EventZIPCode>35212</EventZIPCode>

<EventCountry></EventCountry>

<FirmName></FirmName>

<Name></Name>

<AuthorizedAgent>false</AuthorizedAgent>

<EventCode>01</EventCode>

<EventStatusCategory>CMCXXXX Delivered</EventStatusCategory>

</TrackSummary>

</TrackInfo>

</TrackResponse>

 

Error Response:

<TrackResponse>

<TrackInfo ID="XXXXXXXXXXXXXXXXXX">

<Error>

<Number>-2147219283</Number>

<Description>A status update is not yet available on your Priority Mail Express<SUP>&reg;</SUP> package. It will be available when the shipper provides an update or the package is delivered to USPS. Check back soon. Sign up for Informed Delivery<SUP>&reg;</SUP> to receive notifications for packages addressed to you.</Description>

<HelpFile/>

<HelpContext/>

</Error>

</TrackInfo>

 

4.0   Track and Confirm by Email API

4.1    Overview

The Track and Confirm by Email API allows the customer to submit their email address to be notified of current or future tracking activity. When you request access for this API, please identify your anticipated API volume, mailer ID and how you will be utilizing this API. A mailer identification number (MID) is a 6 or 9-digit number assigned to a customer through the USPS Business Customer Gateway (BCG). Please refer to the following links for help:

 

4.1.1   API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=PTSEmail

&XML=(see below)

4.2    Request Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSEmailRequest

Required

API=PTSEmail.

(Alias)

 

PTSEmailRequest / USERID

Required

This attribute specifies your Web Tools ID. See the Developers Guide for information on obtaining your USERID.

For Example: <USERID=”XXXXXXXXXXXX”>

String

minOccurs="1"

PTSEmailRequest / TrackId

Required

Must be alphanumeric characters.

For example: <TrackId>EJ123456780US</TrackId>

String

minOccurs="1"

PTSEmailRequest / ClientIp

Optional

User IP address. 

For example: <ClientIp>127.0.0.0</ClientIp>

String

minOccurs="0"

PTSEmailRequest / SourceId

Optional

Internal User Identification. 

For example: <SourceId>XYZ Corp</SourceId>

String

minOccurs="0"

PTSEmailRequest / MpSuffix

Required

MPSUFFIX value located in Track/Confirm Fields API response data. Unique to each TrackID.

For example: <MpSuffix>9402</MpSuffix>

Integer

minOccurs="1"

PTSEmailRequest / MpDate

Required

MPDATE value located in Track/Confirm Fields API response data. Unique to each TrackId.

For example: <MpDate>2009-07-02 00:42:23.35744</MpDate>

String

minOccurs="1"

PTSEmailRequest / RequestType

Required once,repeating up to 5 times

Enter a notification request type from the choices available.

Request Type

Descriptions

“AL” 

E-Mail Alert

“FD” 

E-Mail Future Delivery

“ED” 

E-Mail Delivery/Non Delivery activity

“TD” 

E-Mail Today Delivery

“UP”

E-Mail Available for Pickup

“FS”

Package addressed to me/myusps only

“OA”

Other Activity

For example: <RequestType>ED</RequestType>

String

minOccurs="1"
maxOccurs =”5”

Enumerations=

·         AL

·         FD

·         ED

·         TD

·         UP

·         FS

·         OA

PTSEmailRequest / FirstName

Optional

Recipient First Name.

For example: <FirstName>John</FirstName>

String

minOccurs="0"

PTSEmailRequest / LastName

Optional

Recipient Last Name.

For example: <LastName>Doe</LastName>

String

minOccurs="0"

PTSEmailRequest / Email1

Required

Complete valid e-mail address is Required if tag is used.

For example: <Email1>cpapple@email.com</Email1>

String

minOccurs="1"

PTSEmailRequest / Email2

Optional

Complete valid e-mail address is Required if tag is used.

String

minOccurs="0"

PTSEmailRequest / Email3

Optional

Complete valid e-mail address is Required if tag is used.

String

minOccurs="0"

PTSEmailRequest

Required once

API=PTSEmail

(Alias)

 

4.2.1   Sample Request

Request: PTSEmail

<PTSEmailRequest USERID="XXXXXXXXXXXX">

<TrackId>XXXXXXXXXXX</TrackId >

<ClientIp>127.2.0.1</ClientIp>

<SourceId>XYZ Corp</SourceId>

<MpSuffix >9402</MpSuffix>

<MpDate >2009-07-02 00:42:23.35744</MpDate>

<RequestType>EN</RequestType>

<FirstName>John</FirstName>

<LastName >Doe</LastName>

<Email1>test@email.com</Email1>

<Email2></Email2>

<Email3></Email3>

</PTSEmailRequest>

4.3    Response Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSEmailResponse

Required

 

(Alias)

 

PTSEmailResponse / ResultText

Required

Status message.

String

 

PTSEmailRequest