Track & Confirm

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 2.0 (1/26/2014)

 

 

 

 

 

 

United States Postal Service Logo 

 

 

 



To Our Customers

In registering for use of the USPS Web Tools™ (Web Tools), you received a user ID that will allow you to begin sending calls to the server when you are ready.  Any additional information or contact with you will occur as indicated on the registration form, please return to the eCommerce API Technical Guides site for the most recent documentation.

If you require technical support, contact the USPS Internet Customer Care Center (ICCC). This office is staffed as follows:

  • Monday through Friday from 8:00 a.m. to 8:30 p.m. Eastern Time 
  • Saturdays from 8:00 a.m. to 6:00 p.m. Eastern Time 
  • Sunday and Postal Holidays - Closed except for the following Holidays: Martin Luther King; President's Day; Columbus Day; & Veteran’s Day with hours from 9:00 a.m. to 6:00 p.m. ET.

 

E-mail address:  uspstechnicalsupport@mailps.custhelp.com

Telephone: 1-800-344-7779

 

USPS Customer Commitment

The United States Postal Service fully understands the importance of providing information and service anytime day or night to your Internet and e-commerce customers.  For that reason, the USPS is committed to providing 24 x 7 service from our Web Tools servers, 365 days a year.

Registered Trademarks

Priority Mail, Priority Mail Flat Rate, Priority Mail International, Priority Mail Regional Rate, Global Express Mail, Global Express Guaranteed, Global Priority Mail, Parcel Post, Parcel Select, First-Class Mail, USPS, USPS Web Tools, and ZIP + 4 are registered trademarks of the U.S. Postal Service.

Priority Mail Express, Priority Mail Express 1-Day, Priority Mail Express 2-Day, Priority Mail Express 3-Day, Priority Mail Express DPO, Priority Mail Express International, Priority Mail Express Intl, Priority Mail Express Military, Priority Mail Express Offshore, Priority Mail 1-Day, Priority Mail 2-Day, Priority Mail 3-Day, Priority Mail DPO, Priority Mail Intl, Priority Mail Military, Priority Mail Offshore, Signature Confirmation, Standard Post, USPS Tracking, ZIP, and ZIP Code are trademarks of the U.S. Postal Service.

Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.

Adobe Acrobat and Adobe Reader are trademarks of Adobe Systems Incorporated.

DUNS is a registered trademark of Dun & Bradstreet.

 

ãCopyright 2013 United States Postal Service


 

Table of Contents

1.0       Structure of this Guide. 4

2.0       Track/Confirm Web Tool 4

2.1           Track/Confirm Request 4

2.1.1     API Signature. 4

2.1.2     Request Parameters. 5

2.1.3     Request Example. 5

2.2           Track/Confirm WebTool Response. 5

2.2.1     Response Parameters. 5

2.2.2     Response Example. 6

3.0       Track/Confirm Fields Web Tool 7

3.1           Track/Confirm Fields Request 7

3.1.1     API Signature. 7

3.1.2     Request Parameters. 7

3.1.3     Request Example – Revision <> 1. 8

3.1.4     Request Example – Revision = 1. 8

3.2           Track/Confirm Fields Response. 9

3.2.1     Response Parameters – Revision <> 1. 9

3.2.2     Response Example – Revision <> 1. 11

3.2.3     Response Parameters – Revision = 1. 13

3.2.4     Response Example – Revision = 1. 17

4.0       Tracking Service APIs. 22

5.0       Track and Confirm by Email API 22

5.1           Track and Confirm by Email Request 22

5.1.1     API Signature. 22

5.1.2     Request Parameters. 23

5.1.3     Request Example. 24

5.2           Track and Confirm by Email Response. 25

5.2.1     Response Parameters. 25

5.2.2     Response Example. 25

6.0       Proof of Delivery API 26

6.1           Proof of Delivery Request 26

6.1.1     API Signature. 26

6.1.2     Request Parameters. 26

6.1.3     Request Example. 28

6.2           Proof of Delivery Response. 29

6.2.1     Response Parameters. 29

6.2.2     Response Example. 29

7.0       Return Receipt Electronic API 30

7.1           Return Receipt Electronic Request 30

7.1.1     API Signature. 30

7.1.2     Request Parameters. 30

7.1.3     Request Example. 32

7.2           Return Receipt Electronic Response. 32

7.2.1     Response Parameters. 32

7.2.2     Response Example. 32

8.0       Restore API 33

8.1           Restore Request 33

8.1.1     API Signature. 33

8.1.2     Request Parameters. 33

8.1.3     Request Example. 34

8.2           Restore Response. 35

8.2.1     Response Parameters. 35

8.2.2     Response Example. 35

 


1.0    Structure of this Guide

This document provides guidance and step-by-step instructions for installing the Track/Confirm Web Tools and fulfilling various administrative requirements.  There are six separate Web Tools that can be implemented:

§  Track/Confirm Web Tool, which lets customers determine the delivery status of their Priority Mail and Package Services packages with Delivery Confirmation.

§  Track/Confirm Fields Web Tool, which is identical to the Track/Confirm request, except that the request name and the return information data are broken down into fields instead of just one line of text.

§  Tracking Service WebTools, which are offered in conjunction with Revision 1 of the Track/Confirm Fields Web Tool: Track and Confirm by Email, Proof of Delivery, Return Receipt Electronic and Restore for tracking information. 

Each Web Tool is described in its own section.  The steps must be followed in the order presented.

2.0    Track/Confirm Web Tool

Image of hand holding scanning device.The Track/Confirm Web Tool lets customers determine the delivery status of their Priority Mail, Express Mail, and Package Services (Standard Post, Bound Printed Matter, Library Mail, and Media Mail) packages with Delivery Confirmation.  It will also provide tracking data right from your web site, without making your customer go to the USPS web site.  Additionally, the Track/Confirm Web Tool can be appended to your Intranet, allowing, for example, a customer service representative to answer customer queries about the status of their shipments.  The Web Tool Server returns tracking and/or delivery confirmation information for packages requested by the client.  The Track/Confirm Web Tool limits the data requested to ten (10) packages per transaction.

Note: The data returned by the Track/Confirm Web Tool is intended for display only.  The content or sequence of the string data returned by the Web Tool 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 Web Tool.

2.1    Track/Confirm Request

2.1.1        API Signature

Scheme

Host

Path

API

XML

http://

SERVERNAME

/ShippingAPITest.dll

?API=TrackV2

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

2.1.2        Request Parameters

Tag Name

Occurs

Description

Type

TrackRequest

required  

 

(group)

TrackRequest / @USERID

required

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

 

For Example:

<TrackRequest USERID=”yourID”>

string

TrackRequest / TrackID

required

Must be alphanumeric characters.

 

For example: 

<TrackID ID="EJ123456780US">

</TrackID>

string

 

2.1.3        Request Example

 

<TrackRequest USERID=”xxxxxxxx”>

<TrackID ID="EJ123456780US"></TrackID>

<TrackID ID="EJ123456781US"></TrackID>

<TrackID ID="12345"></TrackID>

</TrackRequest>

 

 

2.2    Track/Confirm WebTool Response

2.2.1        Response Parameters

Tag Name

Occurs

Description

Type

TrackResponse

required  

 

(group)

TrackResponse /

TrackInfo

required

 

(group)

TrackResponse /

TrackInfo / @ID="#######"

required

Package Tracking ID Number

string

TrackResponse /  TrackInfo / GuaranteedDeliveryDate

optional

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

string

TrackResponse / TrackInfo / TrackSummary

required

Tracking Summary Information

string

TrackResponse / TrackInfo / TrackDetail

required

Tracking Detail Information

string

 

2.2.2        Response Example

 

<TrackResponse>

<TrackInfo ID="E123456780US">

<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="E123456781US">

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

</TrackInfo>

<TrackInfo ID="12345">

<TrackSummary> That's not a valid number. Please check to make sure you entered it correctly.</TrackSummary>

</TrackInfo>

</TrackResponse>

 

 

If an error message is returned, refer to the Error Responses section for an explanation.

 


3.0    Image of hand holding scanning device.Track/Confirm Fields Web Tool

The Track/Confirm Fields request is identical to the Track/Confirm request except for the request 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 request input to the Web Tool server.

3.1    Track/Confirm Fields Request

3.1.1        API Signature

Scheme

Host

Path

API

XML

http://

SERVERNAME

/ShippingAPITest.dll

?API=TrackV2

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

3.1.2        Request Parameters

Tag Name

Occurs

Description

Type

TrackFieldRequest

required once

 

(group)

TrackFieldRequest / @USERID

required

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

 

For Example:

<TrackFieldRequest USERID=”yourID”>

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 trigger new functionality.

 

For example: 

<Revision>1</Revision>

integer

TrackFieldRequest / ClientIp

optional

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

 

For Example:

<ClientIp>127.0.0.1</ClientIp>

string

TrackFieldRequest / SourceId

optional

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

 

For Example:

<SourceId>XYZ Corp</SourceId>

String

 

TrackFieldRequest / TrackID

required

Package Tracking ID.  Must be alphanumeric characters.

 

For example: 

<TrackID ID="EJ123456780US">

</TrackID>

string

TrackFieldRequest /

TrackID /  DestinationZipCode

optional

5 digit destination zip code.

 

For Example:

<DestinationZipCode>12345</DestinationZipCode>

string

TrackFieldRequest /

TrackID /

MailingDate

optional

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

 

For Example:

<MailingDate>2010-01-01</MailingDate>

string

 

3.1.3        Request Example – Revision <> 1

 

<TrackFieldRequest USERID=" xxxxxxxx">

    <TrackID ID="01805213907042762274">

        <DestinationZipCode>12345</DestinationZipCode>

        <MailingDate>2010-01-01</MailingDate>

   </TrackID>

</TrackFieldRequest>

 

 

3.1.4        Request Example – Revision = 1

 

<TrackFieldRequest USERID="xxxxxxxx">

<Revision>1</Revision>

<ClientIp>127.0.0.1</ClientIp>

<SourceId>John Doe</SourceId>

    <TrackID ID="010850921250125054">

        <DestinationZipCode>12345</DestinationZipCode>

        <MailingDate>2010-01-01</MailingDate>

   </TrackID>

</TrackFieldRequest>


3.2    Track/Confirm Fields Response

3.2.1        Response Parameters – Revision <> 1

Tag Name

Occurs

Description

Type

TrackResponse

required once

 

(group)

TrackResponse / TrackInfo

required

 

(group)

TrackResponse / TrackInfo / @ID="#######"

required

Package Tracking ID number. 

string

TrackResponse / TrackInfo / GuaranteedDeliveryDate

optional

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

string

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

The city where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary / EventState

required

The state where the event occurred.

string

TrackResponse / TrackInfo / TrackSummary /  EventZIPCode

required

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 name of the persons signing for delivery (if available).

string

TrackResponse / TrackInfo / TrackSummary /  AuthorizedAgent

optional

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

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

 


 

3.2.2        Response Example – Revision <> 1

 

<TrackResponse>

  <TrackInfo ID="01805213907042762274">

    <TrackSummary>

      <EventTime>12:12 pm</EventTime>

      <EventDate>May 21, 2001</EventDate>

      <Event>DELIVERED</Event>

      <EventCity>NEWTON</EventCity>

      <EventState>IA</EventState>

      <EventZIPCode>50208</EventZIPCode>

      <EventCountry/>

      <FirmName></FirmName>

      <Name></Name>

      <AuthorizedAgent></AuthorizedAgent>

    </TrackSummary>

    <TrackDetail>

      <EventTime>9:24 pm</EventTime>

      <EventDate>March 28, 2001</EventDate>

      <Event>ENROUTE</Event>

      <EventCity>DES MOINES</EventCity>

      <EventState>IA</EventState>

      <EventZIPCode>50395</EventZIPCode>

      <EventCountry/>

      <FirmName/>

      <Name/>

      <AuthorizedAgent/>

    </TrackDetail>

    <TrackDetail>

      <EventTime>10:00 pm</EventTime>

      <EventDate>March 27, 2001</EventDate>

      <Event>ACCEPTANCE</Event>

      <EventCity>BLAINE</EventCity>

      <EventState>WA</EventState>

      <EventZIPCode>98231</EventZIPCode>

      <EventCountry/>

      <FirmName/>

      <Name/>

      <AuthorizedAgent/>

    </TrackDetail>

  </TrackInfo>

</TrackResponse>

 

 


3.2.3        Response Parameters – Revision = 1

Tag Name

Occurs

Description

Type

TrackResponse

required once

 

(group)

TrackResponse / TrackInfo ID="#######"

required

Package Tracking ID number. 

string

TrackResponse / TrackInfo /  AdditionalInfo

optional

Additional package information

string

TrackResponse / TrackInfo /  ARCHDATA

optional

Internal data availability

boolean

TrackResponse / TrackInfo /  ArchiveRestoreInfo

optional

Information regarding availability of Restore service function

string

TrackResponse / TrackInfo /  AssociatedLabel

optional

Associated label

String

TrackResponse / TrackInfo / CarrierRelease

optional

Indicates whether or not the mailer has authorized carrier release (T or F)

string

TrackResponse / TrackInfo /  Class

optional

The class of mail. Example: Priority Mail 1-Day

string

TrackResponse / TrackInfo /  ClassOfMailCode

optional

Class of mail code  Examples: PM, PME, PMEI

string

TrackResponse / TrackInfo /  DeliveryNotificationDate

optional

Scheduled delivery date

string

TrackResponse / TrackInfo /  DestinationCity

optional

The destination city

string

TrackResponse / TrackInfo /  DestinationCountryCode

optional

The destination country code

string

TrackResponse / TrackInfo /  DestinationState

optional

The destination state

string

TrackResponse / TrackInfo /  DestinationZip

optional

The destination zip code

string

TrackResponse / TrackInfo /  EditedLabelID

Optional, only included in response for specific  SourceIDs

Identifies edited or full barcode information to support numeric only input

string

TrackResponse / TrackInfo /  EmailEnabled

optional

Signifies if Track and Confirm by Email service is enabled

string

TrackResponse / TrackInfo /  ExpectedDeliveryDate

optional

Expected delivery date

string

TrackResponse / TrackInfo /  ExpectedDeliveryTime

optional

Expected delivery time. Example: 2:00 PM

string

TrackResponse / TrackInfo /  GuaranteedDeliveryDate

optional

Guaranteed Delivery Date – Global Express Mail only:  certain countries provide a guarantee delivery. Example: 04 June 2013, 3 Business Days

string

TrackResponse / TrackInfo /  GuaranteedDeliveryTime

optional

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

string

TrackResponse / TrackInfo /  GuaranteedDetails

optional

Messaging to identify Guarantee limits (e.g. Loss Only Guarantee”

string

TrackResponse / TrackInfo /  KahalaIndicator

optional

Indicates if the shipment

string

TrackResponse / TrackInfo /  MailTypeCode

optional

The mail type code

string

TrackResponse / TrackInfo /   MPDATE

optional

Internal date stamp in yyyy-mm-dd hh:mm:ss.xxxx format

string

TrackResponse / TrackInfo /  MPSUFFIX

optional

Internal suffix

integer

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

optional

Signifies if Proof of Delivery service is enabled

boolean

TrackResponse / TrackInfo /  PredictedDeliveryDate

optional

The predicted delivery date

string

TrackResponse / TrackInfo /  RestoreEnabled

optional

Signifies if Restore tracking information service is enabled

boolean

TrackResponse / TrackInfo /  RreEnabled

optional

Signifies if Return Receipt Electronic service is enabled

boolean

TrackResponse / TrackInfo /  Service

optional, repeating up to unbounded times

Additional services purchased

string

TrackResponse / TrackInfo /  ServiceTypeCode

optional

Service Type Code

string

TrackResponse / TrackInfo /  Status

optional

Delivery status

string

TrackResponse / TrackInfo /  StatusCategory

optional

Delivery status category

string

TrackResponse / TrackInfo /  StatusSummary

optional

Detailed status summary

string

TrackResponse / TrackInfo /  TABLECODE

optional

Internal table code

string

TrackResponse / TrackInfo /  ValueofArticle

Optional, only returned for specific  SourceIDs

Declared value of the package contents. Example: $20.00

string

TrackResponse / TrackInfo /  TrackSummary

optional

Tracking Summary Information.

(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 (e.g., Enroute).

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 name of the persons signing for delivery (if available).

string

TrackResponse / TrackInfo /  TrackSummary /  AuthorizedAgent

optional

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

boolean

TrackResponse / TrackInfo /  TrackSummary /  EventCode

optional

Event Code

string

TrackResponse / TrackInfo /  TrackSummary /  ActionCode

optional

Action Code

string

TrackResponse / TrackInfo /  TrackSummary /  ReasonCode

optional

Reason Code

string

TrackResponse / TrackInfo /  TrackDetail

optional

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 (e.g., Enroute).

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

boolean

TrackResponse / TrackInfo /  TrackDetail /  EventCode

optional

Event Code

string

TrackResponse / TrackInfo /  TrackDetail /  ActionCode

optional

Action Code

string

TrackResponse / TrackInfo /  TrackDetail /  ReasonCode

optional

Reason Code

string

 


3.2.4        Response Example – Revision = 1

<?xml version="1.0" ?>

<TrackResponse>

     <TrackInfo ID="9102969010383081813033">

          <Class>Package Services</Class>

          <ClassOfMailCode>BP</ClassOfMailCode>

          <DestinationCity>BEVERLY HILLS</DestinationCity>

          <DestinationState>CA</DestinationState>

          <DestinationZip>90210</DestinationZip>

          <EmailEnabled>true</EmailEnabled>

          <ExpectedDeliveryDate>March 9, 2012</ExpectedDeliveryDate>

          <KahalaIndicator>false</KahalaIndicator>

          <MailTypeCode>DM</MailTypeCode>

          <MPDATE>2012-03-06 03:23:03.300056</MPDATE>

          <MPSUFFIX>9006</MPSUFFIX>

          <OriginCity>LAS VEGAS</OriginCity>

          <OriginState>NV</OriginState>

          <OriginZip>89121</OriginZip>

          <PodEnabled>false</PodEnabled>

          <RestoreEnabled>false</RestoreEnabled>

          <RreEnabled>false</RreEnabled>

          <Service>Delivery Confirmation<SUP>&#153;</SUP></Service>

          <ServiceTypeCode>02</ServiceTypeCode>

          <Status>Delivered</Status>

          <StatusCategory>Delivered</StatusCategory>

          <StatusSummary>Your item was delivered at 9:58 am on March 08, 2012 in BEVERLY HILLS, CA 90210.</StatusSummary>

          <TABLECODE>T</TABLECODE>

          <TrackSummary>

               <EventTime>9:58 am</EventTime>

               <EventDate>March 08, 2012</EventDate>

               <Event>Delivered</Event>

               <EventCity>BEVERLY HILLS</EventCity>

               <EventState>CA</EventState>

               <EventZIPCode>90210</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>01</EventCode>

          </TrackSummary>

          <TrackDetail>

               <EventTime>9:25 am</EventTime>

               <EventDate>March 08, 2012</EventDate>

               <Event>Out for Delivery</Event>

               <EventCity>BEVERLY HILLS</EventCity>

               <EventState>CA</EventState>

               <EventZIPCode>90210</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>OF</EventCode>

          </TrackDetail>

          <TrackDetail>

               <EventTime>9:15 am</EventTime>

               <EventDate>March 08, 2012</EventDate>

               <Event>Sorting Complete</Event>

               <EventCity>BEVERLY HILLS</EventCity>

               <EventState>CA</EventState>

               <EventZIPCode>90210</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>PC</EventCode>

          </TrackDetail>

          <TrackDetail>

               <EventTime>4:47 am</EventTime>

               <EventDate>March 08, 2012</EventDate>

               <Event>Arrival at Post Office</Event>

               <EventCity>BEVERLY HILLS</EventCity>

               <EventState>CA</EventState>

               <EventZIPCode>90210</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>07</EventCode>

          </TrackDetail>

          <TrackDetail>

               <EventTime />

               <EventDate>March 07, 2012</EventDate>

               <Event>Depart USPS Sort Facility</Event>

               <EventCity>BELL GARDENS</EventCity>

               <EventState>CA</EventState>

               <EventZIPCode>90201</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>EF</EventCode>

          </TrackDetail>

          <TrackDetail>

               <EventTime>3:17 am</EventTime>

               <EventDate>March 07, 2012</EventDate>

               <Event>Processed through USPS Sort Facility</Event>

               <EventCity>BELL GARDENS</EventCity>

               <EventState>CA</EventState>

               <EventZIPCode>90201</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>10</EventCode>

          </TrackDetail>

          <TrackDetail>

               <EventTime>4:55 pm</EventTime>

               <EventDate>March 06, 2012</EventDate>

               <Event>Dispatched to Sort Facility</Event>

               <EventCity>LAS VEGAS</EventCity>

               <EventState>NV</EventState>

               <EventZIPCode>89121</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>SF</EventCode>

          </TrackDetail>

          <TrackDetail>

               <EventTime>3:28 pm</EventTime>

               <EventDate>March 06, 2012</EventDate>

               <Event>Acceptance</Event>

               <EventCity>LAS VEGAS</EventCity>

               <EventState>NV</EventState>

               <EventZIPCode>89121</EventZIPCode>

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>03</EventCode>

          </TrackDetail>

          <TrackDetail>

               <EventTime />

               <EventDate>March 06, 2012</EventDate>

               <Event>Electronic Shipping Info Received</Event>

               <EventCity />

               <EventState />

               <EventZIPCode />

               <EventCountry />

               <FirmName />

               <Name />

               <AuthorizedAgent />

               <EventCode>MA</EventCode>

          </TrackDetail>

     </TrackInfo>

</TrackResponse>

 

 

 

If an error message is returned, refer to the Error Responses section for an explanation.


4.0    Image of hand holding scanning device.Tracking Service APIs

Four service APIs are offered in conjunction with “Revision = 1” of the Track/Confirm Fields Web Tool: Track and Confirm by Email, Proof of Delivery, Return Receipt Electronic and Restore for tracking information.  The response data from Track/Confirm Fields request determines which services are available for a tracking ID.  Each request input to the Web Tool server for the tracking service APIs is limited to 1 tracking ID. 

 

These APIs are restricted to USPS internal use only.

 

 

5.0    Track and Confirm by Email API

The Track and Confirm by Email API allows the customer to submit their email address to be notified of current or future tracking activity.

5.1    Track and Confirm by Email Request

The table below presents the XML input tags for generating Live requests and 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.  The Web Tool 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.

 

5.1.1        API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSEmail

&XML=(see below)

 

5.1.2        Request Parameters

Tag Name

Occurs

Description

Type

Validation

PTSEmailRequest

required once

 

(group)

 

PTSEmailRequest / @USERID

required

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

string

 

PTSEmailRequest / @PASSWORD

optional

For backward-compatibility; not validated.

string

 

PTSEmailRequest / TrackId

required

Must be alphanumeric characters.

For example: 

<TrackId>EJ123456780US</TrackId>

string

 

PTSEmailRequest / ClientIp

optional

User IP address. 

 

For Example:

<ClientIp>127.0.0.1</ClientIp>

string

 

PTSEmailRequest / SourceId

optional

Internal User Identification. 

 

For Example:

<SourceId>XYZ Corp</SourceId>

string

 

PTSEmailRequest / MpSuffix

required

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

For Example: <MpSuffix>9402</MpSuffix>

integer

 

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

 

PTSEmailRequest / RequestType

required

Enter a notification request type from the choices available.

 

“EC” – (Email Current) Email all activity to-date

“EN” – (Email New) Email all future tracking activity

“EB” – (Email Both) Email both activity to-date and future tracking activity

For Example:

<RequestType>EC</RequestType>

string

enumeration=EC

enumeration=EN
enumeration=EB  

PTSEmailRequest / FirstName

optional

Recipient First Name.

 

For example: <FirstName>John</FirstName>

string

 

PTSEmailRequest / LastName

optional

Recipient Last Name.

 

For example: <LastName>Doe</LastName>

string

 

PTSEmailRequest / Email1

required once

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

 

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

string

 

PTSEmailRequest / Email2

optional

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

string

 

PTSEmailRequest / Email3

optional

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

string

 

 

5.1.3        Request Example

 

<PTSEmailRequest USERID="xxx">

    <TrackId>01128882300763290532</TrackId >

    <ClientIp>127.0.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> cpapple@email.com </Email1>

    <Email2></Email2>

    <Email3></Email3>

</PTSEmailRequest>

 

 


5.2    Track and Confirm by Email Response

5.2.1        Response Parameters

Tag Name

Occurs

Description

Type

PTSEmailResult

required once

 

(group)

PTSEmailResult / ResultText

required once

Informational text for chosen service option.

string

PTSEmailResult / ReturnCode

required once

Corresponds to <ResultText>.

numeric

 

5.2.2        Response Example

 

 

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

 

 


6.0    Proof of Delivery API

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. 

6.1    Proof of Delivery Request

The table below presents the XML input tags for generating Live requests and 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.  The Web Tool 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.

 

6.1.1        API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSPod

&XML=(see below)

 

6.1.2        Request Parameters

Tag Name

Occurs

Description

Type

Validation

PTSPodRequest

required once

 

(group)

 

PTSPodRequest / @USERID

required

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

string

 

PTSPodRequest / @PASSWORD

optional

For backward-compatibility; not validated.

string

 

PTSPodRequest / TrackId

required

Must be alphanumeric characters.

For example: 

<TrackId>EJ123456780US</TrackId>

string

 

PTSPodRequest / ClientIp

optional

User IP address. 

 

For Example:

<ClientIp>127.0.0.1</ClientIp>

string

 

PTSPodRequest / SourceId

optional

Internal User Identification. 

 

For Example:

<SourceId>XYZ Corp</SourceId>

string

 

PTSPodRequest / MpSuffix

required

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

For Example: <MpSuffix>9402</MpSuffix>

integer

 

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

 

PTSPodRequest / RequestType

required

Enter a notification request type from the choices available.

 

For Example:

<RequestType>Email</RequestType>

string

enumeration=Email

PTSPodRequest / FirstName

required  

Recipient First Name.

 

For example: <FirstName>John</FirstName>

string

 

PTSPodRequest / LastName

required

Recipient Last Name.

 

For example: <LastName>Doe</LastName>

string

 

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

 

PTSPodRequest / Email2

optional

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

string

 

PTSPodRequest / Email3

optional

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

string

 

PTSPodRequest / FaxNumber

optional

Deprecated.  “Fax” option no longer available.

string

 

PTSPodRequest / AddressLine1

optional

Deprecated.  “Mail” option no longer available.

string

 

PTSPodRequest / AddressLine2

optional

Deprecated.  “Mail” option no longer available.

string

 

PTSPodRequest / City

optional

Deprecated.  “Mail” option no longer available.

string

 

PTSPodRequest / State

optional

Deprecated.  “Mail” option no longer available.

string

 

PTSPodRequest / Zip

optional

Deprecated.  “Mail” option no longer available.

string

 

PTSPodRequest / VerifyAddress

optional

Deprecated.  “Mail” option no longer available.

boolean

 

PTSPodRequest / TableCode

required

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

For Example:

<TableCode>T</TableCode>

string

 

 

6.1.3        Request Example

 

<PTSPodRequest USERID="xxx">

    <TrackId>21010521297326074392</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

    <SourceId>XYZ Corp</SourceId>

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

    <TableCode>T</TableCode>

</PTSPodRequest>

 


6.2    Proof of Delivery Response

6.2.1        Response Parameters

Tag Name

Occurs

Description

Type

PTSPodResult

required once

 

(group)

PTSPodResult / AMSMatch

optional

Indicates whether or not a match was found for requested address. 

 

Required when PTSPodRequest[ VerifyAddress=’true’]

string

PTSPodResult / PreferredAddress

optional

Cleansed address response

(group)

PTSPodResult / ADDRESSLINE1

optional

Cleansed address response

string

PTSPodResult / ADDRESSLINE2

optional

Cleansed address response

string

PTSPodResult / CITY

optional

Cleansed address response

string

PTSPodResult / STATE

optional

Cleansed address response

string

PTSPodResult / ZIP

optional

Cleansed address response

string

PTSPodRequest / ResultText

required once

Informational text for chosen service option.

string

PTSPodRequest / ReturnCode

required once

Corresponds to <ResultText>.

numeric

 

6.2.2        Response Example

 

<PTSPodResult>

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

    <ReturnCode>0</ReturnCode>

</PTSPodResult>

 

 

 


7.0    Return Receipt Electronic API

The Return Receipt Electronic API allows the customer to request a copy of the proof of delivery record via email.

7.1    Return Receipt Electronic Request

The table below presents the XML input tags for generating Live requests and 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.  The Web Tool 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.

 

7.1.1        API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSRre

&XML=(see below)

 

7.1.2        Request Parameters

Tag Name

Occurs

Description

Type

Validation

PTSRreRequest

required once

 

(group)

 

PTSRreRequest / @USERID

required

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

string

 

PTSRreRequest / @PASSWORD

optional

For backward-compatibility; not validated.

string

 

PTSRreRequest / TrackId

required

Must be alphanumeric characters.

For example: 

<TrackId>EJ123456780US</TrackId>

string

 

PTSRreRequest / ClientIp

optional

User IP address. 

 

For Example:

<ClientIp>127.0.0.1</ClientIp>

string

 

PTSRreRequest / SourceId

optional

Internal User Identification.  

 

For Example:

<SourceId>XYZ Corp</SourceId>

string

 

PTSRreRequest / MpSuffix

required

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

For Example: <MpSuffix>9402</MpSuffix>

integer

 

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

 

PTSRreRequest / FirstName

required

Recipient First Name.

 

For example: <FirstName>John</FirstName>

string

 

PTSRreRequest / LastName

required

Recipient Last Name.

 

For example: <LastName>Doe</LastName>

string

 

PTSRreRequest / Email1

required once

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

 

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

string

 

PTSRreRequest / Email2

optional

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

string

 

PTSRreRequest / Email3

optional

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

string

 

PTSRreRequest / TableCode

required

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

For Example:

<TableCode>T</TableCode>

string

 

 

 

 

7.1.3        Request Example

 

<PTSRreRequest USERID="xxx">

    <TrackId>05878510510001001318</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>

</PTSRreRequest>

 

 

7.2    Return Receipt Electronic Response

7.2.1        Response Parameters

Tag Name

Occurs

Description

Type

PTSRreResult

required once

 

(group)

PTSRreResult / ResultText

required once

Informational text for chosen service option.

string

PTSRreResult / ReturnCode

required once

Corresponds to <ResultText>.

numeric

7.2.2        Response Example

 

<PTSRreResult>

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

   <ReturnCode>0</ReturnCode>

</PTSRreResult>

 

 


8.0    Restore API

The Restore API allows the customer to restore tracking information from the archives.

8.1    Restore Request

The table below presents the XML input tags for generating Live requests and 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.  The Web Tool 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.

 

8.1.1        API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSRestore

&XML=(see below)

 

8.1.2        Request Parameters

Tag Name

Occurs

Description

Type

Validation

PTSRestoreRequest

required once

 

(group)

 

PTSRestoreRequest / @USERID

required

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

string

 

PTSRestoreRequest / @PASSWORD

optional

For backward-compatibility; not validated.

string

 

PTSRestoreRequest / TrackId

required

Must be alphanumeric characters.

For example: 

<TrackId>EJ123456780US</TrackId>

string

 

PTSRestoreRequest / ClientIp

optional

User IP address. 

 

For Example:

<ClientIp>127.0.0.1</ClientIp>

string

 

PTSRestoreRequest / SourceId

optional

Internal User Identification. 

 

For Example:

<SourceId>XYZ Corp</SourceId>

string

 

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

 

PTSRestoreRequest / FirstName

optional

Recipient First Name.

 

For example: <FirstName>John</FirstName>

string

 

PTSRestoreRequest / LastName

optional

Recipient Last Name.

 

For example: <LastName>Doe</LastName>

string

 

PTSRestoreRequest / Email

optional

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

 

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

string

 

 

8.1.3        Request Example

 

<PTSRestoreRequest USERID="xxx">

    <TrackId>70010320000307851274</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

    <SourceId>XYZ Corp</SourceId>

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

    <FirstName>John</FirstName>

    <LastName>Doe</LastName>

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

</PTSRestoreRequest>

 

 

8.2    Restore Response

8.2.1        Response Parameters

Tag Name

Occurs

Description

Type

PTSRestoreResult

required once

 

(group)

PTSRestoreResult / ResultText

required once

Informational text for chosen service option.

string

PTSRestoreResult / ReturnCode

required once

Corresponds to <ResultText>.

numeric

 

8.2.2        Response Example

 

<PTSRestoreResult>

    <ResultText>Records will generally be restored within four hours. Restored records will be available online for 30 days. Please check back later to view your restored event information.</ResultText>

    <ReturnCode>0</ReturnCode>

</PTSRestoreResult>