Track & Confirm API

 

USPS Web Tools™

Application Programming Interface

User Guide

Version 4.6 (7/13/2023)

 

 

 

 

 

 


 

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 5

2.1         Overview. 5

2.1.1      API Signature Table. 5

2.2         Request Descriptions. 6

2.2.1      Sample Request 6

2.3         Response Descriptions. 6

2.3.1      Sample Response. 7

3.0         Package Tracking “Fields” API 8

3.1         Overview. 8

3.1.1      API Signature. 8

3.2         Request Descriptions. 8

3.2.1      Sample Request 9

3.2         Response Descriptions. 10

3.3.2      Sample Response. 19

4.0         Track and Confirm by Email API 21

4.1         Overview. 21

4.1.1      API Signature. 21

4.2         Request Descriptions. 22

4.2.1      Sample Request 23

4.3         Response Descriptions. 24

4.3.1      Sample Response. 24

5.0         Proof of Delivery API 24

5.1         Overview. 24

5.1.1      API Signature. 25

5.2         Request Descriptions. 25

5.2.1      Sample Request 27

5.3         Response Descriptions. 27

5.3.1      Sample Response. 28

6.0         Return Receipt Electronic API 28

6.1         Overview. 28

6.1.1      API Signature. 28

6.2         Request Descriptions. 28

6.2.1      Sample Request 30

6.3         Response Descriptions. 30

6.3.1      Sample Response. 30

7.0         Track Proof of Delivery API 30

7.1         Overview. 30

7.1.1      API Signature. 31

7.2         Request Descriptions. 31

7.2.1      Sample Request 33

7.3         Response Descriptions. 33

7.3.1      Sample Response. 33

 


 

1.0   Introduction

This document contains a Reference Guide to the USPS Tracking/Delivery Confirmation Label APIs. See the Developer's 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

To obtain Package Tracking API (API=TrackV2) access, users will need to follow the below steps.

 

1.      Register for Web Tools at https://registration.shippingapis.com/.

2.      Obtain a valid registered mailer identification number (MID). This 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.

o   https://gateway.usps.com/eAdmin/view/knowledge?securityId=MID

o   https://postalpro.usps.com/mailing/mailer-id  

Important Note: Set up of your MID must be completed prior to requesting access or your request will be rejected. Please contact the NCSC-Delivery Confirmation (email: Delivery.confirmation@usps.gov; phone: 1-877-264-9693, Option 1) for assistance.

3.      Once the above steps are completed submit your Package Tracking access request at: https://usps.force.com/emailus/s/web-tools-inquiry and provide your Web Tools user ID, select ‘Tracking APIs’, select ‘Access for Tracking APIs’ and submit the following information below in the “Additional Information” text box:

·        Web Tools User ID:

·        Mailer ID (MID):

·        Company Name:

·        Company Website:

·        Requester First and Last Name:

·        Requester Email:

·        Requester Phone number:

·        Mailing Address:

·        Mailing City:

·        Mailing State:

·        Mailing Zip Code:

·        Web Tools Registration Date:

·        API access requested: Package Tracking (API=TrackV2)

·        Anticipated volume: (daily, weekly, monthly, or annually)

·        Shipping done with USPS: Please describe.

·        Any additional information:

Four service APIs are offered in conjunction with “Revision=1” of the Package Tracking “Fields” API: Track and Confirm by Email (PTSEmail), Proof of Delivery (PTSPod), Track Proof of Delivery (PTSTPod), and Return Receipt Electronic (PTSRre). 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 and in order to gain access follow the above steps.

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 Web Tools user ID. See the Developer's Guide for information on obtaining your USERID.

For Example: USERID="XXXXXXX"

NMTOKEN

 

TrackRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password.

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

TrackRequest / TrackID

Required

Must be alphanumeric characters.

For example:  <TrackID ID="EJ123456780US">

</TrackID>

String

minOccurs="1"

2.2.1   Sample Request

Request: Package Track

<TrackRequest USERID="XXXXXXXXX" PASSWORD="">

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

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

</TrackRequest>

 

2.3     Response Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

TrackResponse

Required

 

(Alias)

 

TrackResponse / TrackInfo

Required

max 10

 

(Group)

 

TrackResponse / TrackInfo ID

Required

Tracking ID

Token

 

TrackResponse / TrackInfo / DeliveryNotificationDate

Optional

 

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 user ID. See the Developer’s Guide for information on obtaining your USERID.

For Example: USERID="XXXXXXX"

NMTOKEN

 

TrackFieldRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password.

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

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’s IP address. ClientIP is required when <Revision>=1

For example: <ClientIp>137.0.0.1</ClientIp>

 

Note: Web Tools will always collect the physical IP address from the system generating the API call. This will be passed on the backend to a separate internal package tracking system.

String

minOccurs="0"

TrackFieldRequest / SourceId

Required

External integrators should pass company name. SourceID is required when <Revision>=1.

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

API=TrackV2

(Alias)

 

3.2.1   Sample Request

Request: Track and Confirm

<TrackFieldRequest USERID="XXXXXXXXX" PASSWORD="">

<Revision>1</Revision>

<ClientIp>122.3.3</ClientIp>

<SourceId>XYZ Corp</SourceId>

<TrackID ID="xxxxxxxxxxxxxxxxxxx"/>

</TrackFieldRequest>

 


 

3.2     Response Descriptions

 

Tag Name

Occurs

Descriptions

Type

Validation

TrackResponse / TrackInfo ID

Required

The tracking number ID submitted through the request

For example: EA123456795US

12887393000019

String

 

TrackResponse / TrackInfo / AdditionalInfo

Optional

 

Additional package information

String

 

TrackResponse / TrackInfo / ADPScripting

Optional

 

Additional ADP scripting specific to the ADP Type code

String

 

TrackResponse / TrackInfo / ArchiveRestoreInfo

Optional

 

Information regarding availability of Restore service function 

For example Yes

String

 

TrackResponse / TrackInfo / AssociatedLabel

Optional

 

Additional Label on the mail piece

For example: EA123456785US

This is not currently populated.

String

 

TrackResponse / TrackInfo / CarrierRelease

Optional

 

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

Boolean

Enumerations=

·        True

·        False

TrackResponse / TrackInfo / Class

Optional

 

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

String

 

TrackResponse / TrackInfo / ClassofMailCode

Optional

 

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

String

 

TrackResponse / TrackInfo / DestinationCity

Optional

 

The destination city. For example: Rochester

String

 

TrackResponse / TrackInfo / DestinationCountryCode

Optional

 

The destination country code.  For example: MX, CA

String

 

TrackResponse / TrackInfo / DestinationState

Optional

 

The destination state. For example: NY

String

 

TrackResponse / TrackInfo / DestinationZip

Optional

 

The destination ZIP code. For example:20024

String

 

TrackResponse / TrackInfo / EditedLabelID

Optional, used only when Source ID is IVR

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

String

 

TrackResponse / TrackInfo / EmailEnabled

Optional

 

Signifies if USPS Tracking by Email service is enabled.

Boolean

Enumeration

·        True

·        False

TrackResponse / TrackInfo / EndOfDay

Optional

 

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

 

TrackResponse / TrackInfo / eSOFEligible

Optional

 

Signifies if the mailpiece is eSOF eligibile.

Boolean

Enumeration

·        True

·        False

TrackResponse / TrackInfo / ExpectedDeliveryDate

Optional

 

Expected delivery date. For example:December 31, 2013

String

 

TrackResponse / TrackInfo / ExpectedDeliveryTime

Optional

 

Expected Delivery Time. For example: 3:00 PM

String

 

TrackResponse / TrackInfo / ExpectedDeliveryType

Optional

 

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

String

 

TrackResponse / TrackInfo / GuaranteedDeliveryDate

Optional

 

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

For example: April 15, 2011 or 3 Business Days

String

 

TrackResponse / TrackInfo / GuaranteedDeliveryTime

Optional

 

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

String

 

TrackResponse / TrackInfo / GuaranteedDeliveryType

Optional

 

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

String

 

TrackResponse / TrackInfo / GuaranteedDetails

Optional

 

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

String

 

TrackResponse / TrackInfo / KahalaIndicator

Optional

 

 

Boolean

Enumeration:

·        True

·        False

TrackResponse / TrackInfo / MailTypeCode

Optional

 

For internal USPS use only

String

 

TrackResponse / TrackInfo / MPDATE

Optional

 

Internal date stamp.

2010-03-30 19:30:48.224343

String

 

TrackResponse / TrackInfo / MPSUFFIX

Optional

 

Internal suffix.

Integer

 

TrackResponse / TrackInfo / OnTime

Optional

 

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

Boolean

Enumeration:

·        True

·        False

TrackResponse / TrackInfo / OriginCity

Optional

 

The origin city

String

 

TrackResponse / TrackInfo / OriginCountryCode

Optional

 

The origin country code

String

 

TrackResponse / TrackInfo / OriginState

Optional

 

The origin state

String

 

TrackResponse / TrackInfo / OriginZip

Optional

 

The origin ZIP code

String

 

TrackResponse / TrackInfo / PredictedDeliveryDate

Optional

 

Predicted delivery date. December 30, 2013

String

 

TrackResponse / TrackInfo / PredictedDeliveryTime

Optional

 

Predicted Delivery Time 3:00 PM or blank.

String

 

TrackResponse / 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

 

TrackResponse / TrackInfo / PredictedDeliverySource

Optional

 

States which system provided the Predicted Delivery prediction.

TRP, AA

String

 

TrackResponse / 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

 

TrackResponse / 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

 

TrackResponse / TrackInfo / PurgeByDate

Optional

 

Contains the Purge By Date of the mail piece.

Example: December 31, 2024

String

 

TrackResponse / 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

 

TrackResponse / TrackInfo / RestoreEnabled

Optional

 

Signifies if Restore tracking information service is enabled

Boolean

Enumeration:

·        True

·        False

TrackResponse / TrackInfo / ReturnDateNotice

Optional

 

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

String

 

TrackResponse / TrackInfo / PodEnabled

Optional

 

Signifies if Proof of Delivery service is enabled.

Boolean

Enumeration:

·        True

·        False

TrackResponse / TrackInfo / TpodEnabled

Optional

 

Signifies if Tracking Proof of Delivery service is enabled

Boolean

Enumeration=

·        True

·        False

TrackResponse / TrackInfo / RramEnabled

Optional

 

Signifies if RRAM service is enabled

Boolean

Enumeration:

·        True

·        False

TrackResponse / TrackInfo / RreEnabled

Optional

 

Signifies if Return Receipt Electronic service is enabled

Boolean

Enumeration:

·        True

·        False

TrackResponse / TrackInfo / Service

Optional

Unbounded

 

Additional services purchased

String

 

TrackResponse / TrackInfo / ServiceTypeCode

Optional

max 1

 

Service Type Code of the mail piece

M, AD, VI, 03, 70, 716

String

 

TrackResponse / TrackInfo / Status

Optional

 

For example: Delivered

String

 

TrackResponse / TrackInfo / StatusCategory

Optional

 

For example: In Transit

String

 

TrackResponse / TrackInfo / StatusSummary

Optional

 

Status summary

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

String

 

TrackResponse / 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

 

TrackResponse / TrackInfo / ValueofArticle <placeholder>

Optional

 

Value of Article for when the Source ID is PIN

String

 

TrackResponse / TrackInfo / ProductWeight

Optional

 

Product weight in ounces

String

 

TrackResponse / TrackInfo / TrackSummary

Conditional Required

max 1

Tracking Summary Information. The group is listed once.

(group)

 

TrackResponse / TrackInfo / TrackSummary / EventTime

Optional

The time of the event.

String

 

TrackResponse / TrackInfo / TrackSummary / EventDate

Optional

The date of the event.

String

 

TrackResponse / TrackInfo / TrackSummary / Event

Optional

The event type

String

 

TrackResponse / TrackInfo / TrackSummary / EventCity

Optional

The city where the event occurred.

String

 

TrackResponse / TrackInfo / TrackSummary / EventState

Optional

The state where the event occurred.

String

 

TrackResponse / TrackInfo / TrackSummary / EventZIPCode

Optional

The ZIP Code of the event.

String

 

TrackResponse / TrackInfo / TrackSummary / EventCountry

Optional

The country where the event occurred.

String

 

TrackResponse / TrackInfo / TrackSummary / FirmName

Optional

The company name if delivered to a company.

String

 

TrackResponse / TrackInfo / TrackSummary / Name

Optional

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

String

 

TrackResults / TrackInfo / TrackSummary / AuthorizedAgent

Optional

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

Boolean

Enumerations=

·        True

·        False

TrackResponse / TrackInfo / TrackSummary / EventCode

Optional

The event code

String

 

TrackResponse / TrackInfo / TrackSummary / ActionCode

Optional

max 1

The action code

String

 

TrackResponse / TrackInfo / TrackSummary / ReasonCode

Optional

The reason code

String

 

TrackResponse / TrackInfo / TrackSummary / GeoCertified

Optional

Only eligible to display with delivery (01) events.

Boolean

Enumeration=

·        True

·        False

TrackResults / TrackInfo / TrackSummary / DeliveryAttributeCode

Optional

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

String

 

TrackResults / TrackInfo / TrackSummary / EventStatusCategory

Optional

The status of a posted event on a mail piece.

String

 

TrackResults / TrackInfo / TrackSummary / GMT

Optional

Greenwich Mean Time

String

 

TrackResults / TrackInfo / TrackSummary / GMTOffset

Optional

Greenwich Mean Time Offset

String

 

TrackResults / TrackInfo / TrackSummary / CODAmountDue

Optional

Collect on Delivery (COD) amount

String

 

TrackResponse / TrackInfo / TrackDetail

Optional

max 99

Tracking Detail Information. This group is repeatable.

(group)

 

TrackResponse / TrackInfo / TrackDetail / EventTime

Optional

The time of the event.

String

 

TrackResponse / TrackInfo / TrackDetail / EventDate

Optional

The date of the event.

String

 

TrackResponse / TrackInfo / TrackDetail / Event

Optional

The event type

String

 

TrackResponse / TrackInfo / TrackDetail / EventCity

Optional

The city where the event occurred.

String

 

TrackResponse / TrackInfo / TrackDetail / EventState

Optional

The state where the event occurred.

String

 

TrackResponse / TrackInfo / TrackDetail / EventZIPCode

Optional

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 first initial and last name of the person 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

TrackResponse / TrackInfo / TrackDetail / EventCode

Optional

The event code

String

 

TrackResponse / TrackInfo / TrackDetail / ActionCode

Optional

max 1

The action code

String

 

TrackResponse / TrackInfo / TrackDetail / ReasonCode

Optional

The reason code

String

 

TrackResponse / TrackInfo / TrackDetail / GeoCertified

Optional

Only eligible to display with delivery (01) events.

Boolean

Enumeration=

·        True

·        False

TrackResults / TrackInfo / TrackDetail / DeliveryAttributeCode

Optional

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

String

 

TrackResults / TrackInfo / TrackDetail / EventStatusCategory

Optional

The status of a posted event on a mail piece.

String

 

TrackResults / TrackInfo / TrackDetail / GMT

Optional

Greenwich Mean Time

String

 

TrackResults / TrackInfo / TrackDetail / GMTOffset

Optional

Greenwich Mean Time Offset

String

 

TrackResults / TrackInfo / TrackDetail / CODAmountDue

Optional

Collect on Delivery (COD) amount

String

 

TrackResponse / TrackInfo / Error

Optional

Error message grouping if applicable.

(Group)

 

TrackResponse / TrackInfo / Error / Number

Optional

Unique number assigned for the type of error that has occurred.

String

 

TrackResponse / TrackInfo / Error / Description

Optional

Error message description

 

Example: <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>

String

 

3.3.2   Sample Response

Response: Package Tracking “Fields”

<TrackResponse>

    <TrackInfo ID=" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ">

        <GuaranteedDeliveryDate>June 24, 2022</GuaranteedDeliveryDate>

        <TrackSummary>

            <EventTime>9:00 am</EventTime>

            <EventDate>June 22, 2022</EventDate>

            <Event>Delivered, To Agent</Event>

            <EventCity>AMARILLO</EventCity>

            <EventState>TX</EventState>

            <EventZIPCode>79109</EventZIPCode>

            <EventCountry/>

            <FirmName/>

            <Name>RXXXXXX XXXXXXX</Name>

            <AuthorizedAgent>false</AuthorizedAgent>

            <DeliveryAttributeCode/>

            <GMT>14:00:00</GMT>

            <GMTOffset>-05:00</GMTOffset>

        </TrackSummary>

        <TrackDetail>

            <EventTime/>

            <EventDate>June 22, 2022</EventDate>

            <Event>USPS expects item for mailing (SSK)</Event>

            <EventCity>LAUREL</EventCity>

            <EventState>MD</EventState>

            <EventZIPCode>20707</EventZIPCode>

            <EventCountry/>

            <FirmName/>

            <Name/>

            <AuthorizedAgent>false</AuthorizedAgent>

            <GMT/>

            <GMTOffset/>

        </TrackDetail>

    </TrackInfo>

</TrackResponse>

 

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

<TrackResponse>

    <TrackInfo ID=" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ">

        <Class>Priority Mail Express 2-Day&lt;SUP>&amp;reg;&lt;/SUP></Class>

        <ClassOfMailCode>EX</ClassOfMailCode>

        <DestinationCity>AMARILLO</DestinationCity>

        <DestinationState>TX</DestinationState>

        <DestinationZip>79109</DestinationZip>

        <EmailEnabled>true</EmailEnabled>

        <GuaranteedDeliveryDate>June 24, 2022</GuaranteedDeliveryDate>

        <GuaranteedDeliveryTime>6:00pm</GuaranteedDeliveryTime>

        <GuaranteedDetails>Money Back Guarantee</GuaranteedDetails>

        <KahalaIndicator>false</KahalaIndicator>

        <MailTypeCode>DM</MailTypeCode>

        <MPDATE>2022-06-24 11:30:26.000000</MPDATE>

        <MPSUFFIX>XXXXXXX</MPSUFFIX>

        <OriginCity>LAUREL</OriginCity>

        <OriginState>MD</OriginState>

        <OriginZip>20707</OriginZip>

        <PodEnabled>true</PodEnabled>

        <TPodEnabled>false</TPodEnabled>

        <RestoreEnabled>false</RestoreEnabled>

        <RramEnabled>false</RramEnabled>

        <RreEnabled>false</RreEnabled>

        <Service>Signature Confirmation&lt;SUP>&amp;#153;&lt;/SUP></Service>

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

        <ServiceTypeCode>889</ServiceTypeCode>

        <Status>Delivered, To Agent</Status>

        <StatusCategory>Delivered</StatusCategory>

        <StatusSummary>Your item has been delivered to an agent at 9:00 am on June 22, 2022 in AMARILLO, TX 79109. The item was signed for by R XXXXXXX.</StatusSummary>

        <TABLECODE>T</TABLECODE>

        <TrackSummary>

            <EventTime>9:00 am</EventTime>

            <EventDate>June 22, 2022</EventDate>

            <Event>Delivered, To Agent</Event>

            <EventCity>AMARILLO</EventCity>

            <EventState>TX</EventState>

            <EventZIPCode>79109</EventZIPCode>

            <EventCountry/>

            <FirmName/>

            <Name>RXXXXXX XXXXXXX</Name>

            <AuthorizedAgent>false</AuthorizedAgent>

            <EventCode>01</EventCode>

            <DeliveryAttributeCode/>

            <GMT>14:00:00</GMT>

            <GMTOffset>-05:00</GMTOffset>

        </TrackSummary>

        <TrackDetail>

            <EventTime/>

            <EventDate>June 22, 2022</EventDate>

            <Event>USPS expects item for mailing (SSK)</Event>

            <EventCity>LAUREL</EventCity>

            <EventState>MD</EventState>

            <EventZIPCode>20707</EventZIPCode>

            <EventCountry/>

            <FirmName/>

            <Name/>

            <AuthorizedAgent>false</AuthorizedAgent>

            <EventCode>03</EventCode>

            <GMT/>

            <GMTOffset/>

        </TrackDetail>

    </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 user ID. See the Developer’s Guide for information on obtaining your USERID.

For Example: USERID="XXXXXXX"

NMTOKEN

 

PTSEmailRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password.

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

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="XXXXXXXXX" PASSWORD="">

<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 / ReturnCode

Required

Return code.

Integer

 

PTSEmailResponse

Required

 

(Alias)

 

4.3.1   Sample Response

Response: PTSEmail

<PTSEMAILRESULT>

<ResultText>Your request for all activity to-date will be processed within four hours. Any future activity will be processed whenever there is new delivery related event activity.</ResultText>

<ReturnCode>0</ReturnCode>

</PTSEMAILRESULT>

 

5.0   Proof of Delivery API

5.1     Overview

Proof of Delivery is a letter that includes the recipient's name and a copy of their signature. The Proof of Delivery API allows the customer to request proof of delivery notification via email. 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:

 

5.1.1   API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=PTSPod

&XML=(see below)

5.2     Request Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSPodRequest

Required once

 

(Alias)

 

PTSPodRequest / USERID

Required

This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID.

For Example: USERID="XXXXXXX"

NMTOKEN

 

PTSPodRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password.

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

PTSPodRequest / TrackId

Required

Must be alphanumeric characters.

For example:  <TrackId>EJ123456780US</TrackId>

String

minOccurs="1"

PTSPodRequest / ClientIp

Optional

User IP address. 

For example: <ClientIp>127.0.0.1</ClientIp>

String

minOccurs="0"

PTSPodRequest / SourceId

Optional

Internal User Identification. 

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

String

minOccurs="0"

PTSPodRequest / MpSuffix

Required

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

For example: <MpSuffix>9402</MpSuffix>

integer

minOccurs="1"

PTSPodRequest / 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"

PTSPodRequest / RequestType

Required

Enter a notification request type from the choices available.

For example: <RequestType>Email</RequestType>

String

minOccurs="1"

PTSPodRequest / FirstName

Required 

Recipient First Name.

For example: <FirstName>John</FirstName>

String

minOccurs="1"

PTSPodRequest / LastName

Required

Recipient Last Name.

For example: <LastName>Doe</LastName>

String

minOccurs="1"

PTSPodRequest / Email1

Optional

Required when PTSPodRequest[RequestType=’Email’].

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

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

String

minOccurs="0"

PTSPodRequest / Email2

Optional

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

String

minOccurs="0"

PTSPodRequest / Email3

Optional

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

String

minOccurs="0"

PTSPodRequest / FaxNumber

Optional

Fax Number.

String

minOccurs="0"

PTSPodRequest / AddressLine1

Optional

Address Line 1.

String

minOccurs="0"

PTSPodRequest / AddressLine2

Optional

Address Line 2.

String

minOccurs="0"

PTSPodRequest / City

Optional

City

String

minOccurs="0"

PTSPodRequest / State

Optional

State

String

minOccurs="0"

PTSPodRequest / Zip

Optional

Zip

String

minOccurs="0"

PTSPodRequest / VerifyAddress

Optional

Indicates whether or not address should be validated.

Boolean

minOccurs="0"

PTSPodRequest / TableCode

Required

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

For example: <TableCode>T</TableCode>

String

minOccurs="1"

PTSPodRequest / CustRegID

Optional

Unique 10-byte numeric value that’s associated to each user.

String

minOccurs="0"

PTSPodRequest

Required once

 

(Alias)

 

5.2.1   Sample Request  

Request: PTSPod

<PTSPodRequest USERID="XXXXXXXXX" PASSWORD="">

<TrackId>XXXXXXXXXXX</TrackId >

<ClientIp>127.0.0.1</ClientIp>

<SourceId>XXXXXX</SourceId>

<MpSuffix>9402</MpSuffix>

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

<RequestType>Email</RequestType>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

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

<Email2></Email2>

<Email3></Email3>

<TableCode>T</TableCode>

<CustRegID>1234567890</CustRegID>

</PTSPodRequest>

5.3     Response Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSPODResult

Required

 

(Alias)

 

PTSPODResponse / ResultText

Required

Status message.

String

 

PTSPODRequest / ReturnCode

Required

Return code.

Integer

 

PTSPODResult

Required

 

(Alias)

 

5.3.1   Sample Response

Response: PTSPOD

<PTSPODRESULT>

<ResultText>Your Proof of Delivery record is complete and will be processed shortly.</ResultText>

<ReturnCode>0</ReturnCode>

</PTSPODRESULT>

6.0   Return Receipt Electronic API

6.1     Overview

The Return Receipt Electronic API allows the customer to request a copy of the proof of delivery record via email. 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:

 

6.1.1   API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=PTSRre

&XML=(see below)

6.2     Request Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSRreRequest

Required

API=PTSRre

(Alias)

 

PTSRreRequest / USERID

Required

This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID.

For Example: USERID="XXXXXXX"

NMTOKEN

 

PTSRreRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password.

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

PTSRreRequest / TrackId

Required

Must be alphanumeric characters.

For example:  <TrackId>EJ123456780US</TrackId>

String

minOccurs="1"

PTSRreRequest / ClientIp

Optional

User IP address. 

For example: <ClientIp>127.0.0.1</ClientIp>

String

minOccurs="0"

PTSRreRequest / SourceId

Optional

Internal User Identification. 

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

String

minOccurs="0"

PTSRreRequest / MpSuffix

Required

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

For example: <MpSuffix>9402</MpSuffix>

integer

minOccurs="1"

PTSRreRequest / 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"

PTSRreRequest / FirstName

Required

Recipient First Name.

For example: <FirstName>John</FirstName>

String

minOccurs="1"

PTSRreRequest / LastName

Required

Recipient Last Name.

For example: <LastName>Doe</LastName>

String

minOccurs="1"

PTSRreRequest / Email1

Required

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

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

String

minOccurs="1"

PTSRreRequest / Email2

Optional

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

String

minOccurs="0"

PTSRreRequest / Email3

Optional

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

String

minOccurs="0"

PTSRreRequest / TableCode

Required

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

For example: <TableCode>T</TableCode>

String

minOccurs="1"

PTSRreRequest / CustRegID

Optional

Unique 10-byte numeric value that is associated to each user.

String

minOccurs="0"

PTSRreRequest

Required

 

(Alias)

 

 

6.2.1   Sample Request

Request: PTSRre

<PTSRreRequest USERID="XXXXXXXXX" PASSWORD="">

<TrackId>XXXXXXXXXXX</TrackId >

<ClientIp>127.0.0.1</ClientIp>

<SourceId>XYZ Corp</SourceId>

<MpSuffix>9402</MpSuffix>

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

<FirstName>John</FirstName>

<LastName>Doe</LastName>

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

<Email2></Email2>

<Email3></Email3>

<TableCode>T</TableCode>

<CustRegID>1234567890</CustRegID>

</PTSRreRequest>

 

6.3     Response Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSRreResult

Required

 

(Alias)

 

PTSRreResponse / ResultText

Required

Status message.

String

 

PTSRreRequest / ReturnCode

Required

Return code.

Integer

 

PTSRreResult

Required

 

(Alias)

 

6.3.1   Sample Response

Response: PTSRre

<PTSRRERESULT>

<ResultText>Your Proof of Delivery record is complete and will be processed shortly</ResultText>

<ReturnCode>0</ReturnCode>

</PTSRRERESULT>

7.0   Track Proof of Delivery API

7.1     Overview

Track Proof of Delivery is a letter that includes the recipient's name and a copy of their signature. The Track Proof of Delivery API allows the customer to request proof of delivery notification via email. 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:

 

7.1.1   API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=PTSTPod

&XML=(see below)

7.2     Request Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSTpodRequest

Required

 

(Alias)

 

PTSTpodRequest / USERID

Required

This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID.

For Example: USERID="XXXXXXX"

NMTOKEN

 

PTSTpodRequest / PASSWORD

Optional

This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password.

For Example: PASSWORD="XXXXXXX"

NMTOKEN

 

PTSTpodRequest / TrackId

Required

Must be alphanumeric characters.

For example:  <TrackId>EJ123456780US</TrackId>

String

minOccurs="1"

PTSTpodRequest / MpSuffix

Required

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

For example: <MpSuffix>9402</MpSuffix>

integer

minOccurs="1"

PTSTpodRequest / 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"

PTSTpodRequest / RequestType

Required

Enter a notification request type from the choices available.

For example: <RequestType>Email</RequestType>

String

minOccurs="1"

PTSTpodRequest / FirstName

Required

Recipient First Name.

For example: <FirstName>John</FirstName>

String

minOccurs="1"

PTSTpodRequest / LastName

Required

Recipient Last Name.

For example: <LastName>Doe</LastName>

String

minOccurs="1"

PTSTpodRequest / Email1

Optional

Required when PTSTpodRequest[RequestType=’Email’].

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

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

String

minOccurs="0"

PTSTpodRequest / Email2

Optional

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

String

minOccurs="0"

PTSTpodRequest / Email3

Optional

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

String

minOccurs="0"

PTSTpodRequest / CustRegID

Required

Unique 10-byte numeric value that’s associated to each user.

String

minOccurs="0"

PTSTpodRequest / TableCode

Required

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

For example: <TableCode>T</TableCode>

String

minOccurs="1"

PTSTpodRequest / ClientIp

Optional

User IP address.

For example: <ClientIp>133.2.1.1</ClientIp>

String

minOccurs="0"

PTSTpodRequest / SourceId

Optional

Internal User Identification. Required when TrackFieldRequest[Revision=’1’].

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

String

minOccurs="0"

PTSTpodRequest

Required

 

(alias)

 

7.2.1   Sample Request

Request: PTSTPod

<PTSTpodRequest USERID="XXXXXXXXX" PASSWORD="">

<TrackId>XXXXXXXXXXX</TrackId >

<MpSuffix>9402</MpSuffix>

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

<RequestType>Email</RequestType>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

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

<Email2></Email2>

<Email3></Email3>

<CustRegID>1234567890</CustRegID>

<TableCode>T</TableCode>

<ClientIp>127.0.0.1</ClientIp>

<SourceId>XXXXX</SourceId>

</PTSTpodRequest>

7.3     Response Descriptions

Tag Name

Occurs

Descriptions

Type

Validation

PTSTPODResult

Required

 

(Alias)

 

PTSTPODResponse / ResultText

Required

Status message.

String

 

PTSTpodRequest / ReturnCode

Required

Return code.

Integer

 

PTSTPODResult

Required

 

(Alias)

 

 

7.3.1   Sample Response

Response: PTSTPod

<PTSTPODRESULT>

<ResultText>Your Proof of Delivery record is complete and will be processed shortly.</ResultText>

<ReturnCode>0</ReturnCode>

</PTSTPODRESULT>