Track & Confirm API

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Version 3.4.3 (02/13/2018)

 

 

 

 

 

 

 

 

 

 

 


 


Contents

Introduction to Web Tools. 4

Before you get started: 4

USPS Tracking API 4

Overview.. 4

Secure / Non-secure. 5

Track Request API 6

API Signature. 6

Request Description. 6

Sample Request and Response. 7

Track/Confirm Fields API 8

API Signature. 8

Request Description. 8

Sample Requests. 9

Response Description. 10

Response Description (Revision = 1) 11

Sample Response. 17

Tracking Service APIs. 20

Track and Confirm by Email API 20

API Signature. 20

Request Description. 20

Sample Request and Response. 22

Proof of Delivery API 23

Proof of Delivery Request 23

API Signature. 23

Request Description. 24

Sample Requests and Response. 25

Return Receipt Electronic API 26

Return Receipt Electronic Request 26

API Signature. 26

Request Description. 26

Sample Request and Response. 28

Track Proof of Delivery API 28

Track Proof of Delivery Request 28

API Signature. 29

Request Description. 29

Sample Requests and Response. 30


Introduction to Web Tools

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

 

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

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 Technical Documentation section of the Web Tools page on usps.com/webtools.

Label API access requires extra permissions; contact the Internet Customer Care Center uspstechnicalsupport@mailps.custhelp.com to request access. Indicate “Label API Access” in the subject line and explain in the body of the email:

1.           How the shipper intends to purchase and apply postage to the labels

2.           If the label image provided by the API will be modified in any way by the shipper or the software

USPS Tracking API

Overview

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.

Secure / Non-secure

All requests can be submitted via secure HTTP, (HTTPS). The following MUST be submitted via HTTPS due to the presence of Personally Identifiable Information (PII), contained in the request.

-          Track and Confirm by Email: “PTSEmail

-          Proof of Delivery: “PTSPod

-          Return Receipt Electronic: “PTSRre

 

If these requests are sent via HTTP, the following error will be returned:

<Error>

  <Number>80040B1A</Number>

  <Description>API Authorization failure. PTSPod is not a valid API name for this protocol.     </Description>

  <Source>USPSCOM::DoAuth</Source>

</Error>

 

Only the TrackV2 requests can be sent via HTTP

 

 

 

 

 

 

Track Request API

API Signature

Secure

Scheme

Host

Path

API

XML

https://

stg-secure.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

Non - secure

Scheme

Host

Path

API

XML

http://

stg-production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

Note: The “stg-production.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at uspstechnicalsupport@mailps.custhelp.com.

Request Description

Tag Name

Occurs

Description

Type

Validation

TrackRequest

required 

API=TrackV2

(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

minOccurs="1"

 

 

 

 

 

Sample Request and Response (Note: replace the userid & trackid with your values)

Test XML Request:

http://production.shippingapis.com/ShippingAPI.dll?API=TrackV2&XML=<?xml version="1.0" encoding="UTF-8" ?>

<TrackRequest USERID="xxxxxxxx">

<TrackID ID="XXXXXXXXXXXX1"></TrackID>

<TrackID ID="XXXXXXXXXXXX2"></TrackID>

<TrackID ID="XXXXXXXXXXXX3"></TrackID>

</TrackRequest>

 

Test XML Response:

<TrackResponse>

<TrackInfo ID="XXXXXXXXXXXX1">

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

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

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

</TrackInfo>

</TrackResponse>


 

Track/Confirm Fields API

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.

API Signature

Secure

Scheme

Host

Path

API

XML

https://

stg-secure.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

Non - secure

Scheme

Host

Path

API

XML

http://

stg-production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

http://

production.shippingapis.com

/ShippingAPI.dll

?API=TrackV2

&XML=(see below)

 

Note: The “stg-production.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at uspstechnicalsupport@mailps.custhelp.com

Request Description

Tag Name

Occurs

Description

Type

Validation

TrackFieldRequest

required once

API=TrackV2

(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

minOccurs="0"

TrackFieldRequest / ClientIp

optional

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

 

For Example:

<ClientIp>127.0.0.1</ClientIp>

string

minOccurs="0"

TrackFieldRequest / SourceId

optional

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

 

For Example:

<SourceID>XYZ Corp</SourceID>

String

minOccurs=”0”

TrackFieldRequest / SourceIdZIP

optional

ZIP Code of the requestor.

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 once

 

(alias)

 

 

Sample Requests (Note: replace the userid & trackid with your values)

Test XML Request:

<TrackFieldRequest USERID="xxxxxxxxx">

  <ClientIp>111.0.0.1</ClientIp>

  <TrackID ID="XXXXXXXXXXXXXX1" />

</TrackFieldRequest>

 

Test XML Request (Revision = 1):

http://production.shippingapis.com/ShippingAPI.dll?API=TrackV2&XML=<?xml version="1.0" encoding="UTF-8”?>

<TrackFieldRequest USERID="xxxxxxxx">

  <Revision>1</Revision>

  <ClientIp>111.0.0.1</ClientIp>

  <TrackID ID="XXXXXXXXXXXX1" />

</TrackFieldRequest>

Response Description

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 / TrackSummary /  EventCode

optional

The event code.

string

TrackResponse / TrackInfo / TrackSummary /  ActionCode

optional

The action code.

string

TrackResponse / TrackInfo / TrackSummary /  ReasonCode

optional

The reason code.

string

TrackResponse / TrackInfo / TrackDetail

required once

Tracking Detail Information.  This group is repeatable.

(group)

TrackResponse / TrackInfo / TrackDetail / EventTime

required

The time of the event.

string

TrackResponse / TrackInfo / TrackDetail /  EventDate

required

The date of the event.

string

TrackResponse / TrackInfo / TrackDetail / Event

required

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

string

TrackResponse / TrackInfo /  TrackDetail / EventCity

required

The city where the event occurred.

string

TrackResponse / TrackInfo / TrackDetail / EventState

required

The state where the event occurred.

string

TrackResponse / TrackInfo / TrackDetail /  EventZIPCode

required

The ZIP Code of the event.

string

TrackResponse / TrackInfo / TrackDetail / EventCountry

optional

The country where the event occurred.

string

TrackResponse / TrackInfo / TrackDetail / FirmName

optional

The company name if delivered to a company.

string

TrackResponse / TrackInfo / TrackDetail / Name

optional

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

string

TrackResponse / TrackInfo / TrackDetail /  AuthorizedAgent

optional

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

string

TrackResponse / TrackInfo / TrackDetail /  EventCode

optional

The event code.

string

TrackResponse / TrackInfo / TrackDetail /  ActionCode

optional

The action code.

string

TrackResponse / TrackInfo / TrackDetail /  ReasonCode

optional

The reason code.

string

TrackResponse

required once

 

(alias)

 

Response Description (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 /  ADPScripting

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

optional

Predicted Delivery Time.

Example: 3:00 PM (Or blank)

string

TrackResponse / TrackInfo /  PDWStart

optional

Predicted Delivery Window start time in military format.

Example: 1300

string

TrackResponse / TrackInfo /  PDWEnd

optional

Predicted Delivery Window end time in military format.

Example: 1500

string

TrackResponse / TrackInfo /  RelatedRRID

optional

Related Return Receipt ID.

string

TrackResponse / TrackInfo /  RestoreEnabled

optional

Signifies if Restore tracking information service is enabled.

boolean

TrackResponse / TrackInfo /  RRAMenabled

optional

Signifies if RRAM 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 / TpodEnabled

optional

Signifies if Tracking Proof of Delivery service is enabled.

True\False

boolean

TrackResponse / TrackInfo /  ValueofArticle

Optional, only returned for specific  SourceIDs

Declared value of the package contents. Example: $20.00

string

TrackResponse /
TrackInfo/EnabledNotificationRequests/SMS/FD

optional

Mail piece eligibility for Future Delivery – Expected Delivery Date / Time Updates requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/SMS/AL

optional

Mail piece eligibility for Alert  - Delivery Exception requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /

TrackInfo/EnabledNotificationRequests/SMS/TD

optional

Mail piece eligibility for Today Delivery – Day of Delivery Update requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/SMS/UP

optional

Mail piece eligibility for UP / Mail Pickup – Available for Pickup requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/SMS/DND

optional

Mail piece eligibility for DND – Delivery Activity requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/SMS/FS

optional

Mail piece eligibility for FS– First displayable event for Informed Delivery / MyUSPS only requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/SMS/OA

optional

Mail piece eligibility for OA – In-Transit / Other Activity requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/EMAIL/FD

optional

Mail piece eligibility for Future Delivery – Expected Delivery Date / Time Updates requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/EMAIL/AL

optional

Mail piece eligibility for Alert  - Delivery Exception requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/EMAIL/TD

optional

Mail piece eligibility for Today Delivery – Day of Delivery Update requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/EMAIL/UP

optional

Mail piece eligibility for UP / Mail Pickup – Available for Pickup requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/EMAIL/DND

optional

Mail piece eligibility for DND – Delivery Activity requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/EMAIL/FS

optional

Mail piece eligibility for FS – First displayable event for Informed Delivery / MyUSPS only requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

TrackResponse /
TrackInfo/EnabledNotificationRequests/EMAIL/OA

optional

Mail piece eligibility for OA – In-Transit / Other Activity requests.

 

Passed as a Boolean so option can be disabled if not eligible for request type.

Example: True, False

boolean

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

TrackResults / TrackInfo/ TrackSummary /

GeoCertified

optional

Only eligible to display with delivery (01) events.

True\False

boolean

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

TrackResponse

required

 

(alias)

 

Sample Response (Note: replace the userid & trackid with your values)

Test XML Response:

<TrackResponse>

  <TrackInfo ID="XXXXXXXXXX1">

    <TrackSummary>

      <EventTime>10:45 pm</EventTime>

      <EventDate>January 6, 2016</EventDate>

      <Event>Arrived at USPS Facility</Event>

      <EventCity>COLUMBUS</EventCity>

      <EventState>OH</EventState>

      <EventZIPCode>43218</EventZIPCode>

      <EventCountry></EventCountry>

      <FirmName></FirmName>

      <Name></Name>

      <AuthorizedAgent>false</AuthorizedAgent>

    </TrackSummary>

    <TrackDetail>

      <EventTime>9:10 am</EventTime>

      <EventDate>January 6, 2016</EventDate>

      <Event>Acceptance</Event>

      <EventCity>LAKE CHARLES</EventCity>

      <EventState>IL</EventState>

      <EventZIPCode>12345</EventZIPCode>

      <EventCountry></EventCountry>

      <FirmName></FirmName>

      <Name></Name>

      <AuthorizedAgent>false</AuthorizedAgent>

    </TrackDetail>

  </TrackInfo>

</TrackResponse>

 

Test XML Response(Revision = 1):

<TrackResponse>

  <TrackInfo ID="XXXXXXXXXX1">

    <Class>USPS Retail Ground&amp;#153;</Class>

    <ClassOfMailCode>BP</ClassOfMailCode>

    <DestinationCity>KBEA</DestinationCity>

    <DestinationState>TX</DestinationState>

    <DestinationZip>12345</DestinationZip>

    <EmailEnabled>true</EmailEnabled>

    <KahalaIndicator>false</KahalaIndicator>

    <MailTypeCode>DM</MailTypeCode>

    <MPDATE>2016-01-08 10:34:04.000000</MPDATE>

    <MPSUFFIX>412725500</MPSUFFIX>

    <OriginCity>LAKE CHARLES</OriginCity>

    <OriginState>IL</OriginState>

    <OriginZip>12345</OriginZip>

    <PodEnabled>false</PodEnabled>

    <RestoreEnabled>false</RestoreEnabled>

    <RramEnabled>false</RramEnabled>

    <RreEnabled>false</RreEnabled>

    <Service>USPS Tracking&lt;SUP&gt;&amp;#174;&lt;/SUP&gt;</Service>

    <ServiceTypeCode>346</ServiceTypeCode>

    <Status>Arrived at facility</Status>

    <StatusCategory>In Transit</StatusCategory>

    <StatusSummary>Your item arrived at our USPS facility in COLUMBUS, OH 43218 on January 6, 2016 at 10:45 pm. The item is currently in transit to the destination.</StatusSummary>

    <TABLECODE>T</TABLECODE>

<TpodEnabled>true</TpodEnabled>

<EnabledNotificationRequests>

 <SMS>

          <FD>True</FD>

          <AL>True</AL>

          <TD>True</TD>

          <UP>True</UP>

          <DND>True</DND>

         <FS>True</FS>

         <OA>True</OA>

  </SMS>

  <EMAIL>

          <FD>True</FD>

          <AL>True</AL>

          <TD>True</TD>

          <UP>True</UP>

          <DND>True</DND>

         <FS>True</FS>

         <OA>True</OA>

   </EMAIL>

    <EnabledNotificationRequests/>

<TrackSummary>

      <EventTime>10:45 pm</EventTime>

      <EventDate>January 6, 2016</EventDate>

      <Event>Arrived at USPS Facility</Event>

      <EventCity>COLUMBUS</EventCity>

      <EventState>OH</EventState>

      <EventZIPCode>43218</EventZIPCode>

      <EventCountry></EventCountry>

      <FirmName></FirmName>

      <Name></Name>

      <AuthorizedAgent>false</AuthorizedAgent>

      <EventCode>10</EventCode>

    </TrackSummary>

    <TrackDetail>

      <EventTime>9:10 am</EventTime>

      <EventDate>January 6, 2016</EventDate>

      <Event>Acceptance</Event>

      <EventCity>LAKE CHARLES</EventCity>

      <EventState>IL</EventState>

      <EventZIPCode>12345</EventZIPCode>

      <EventCountry></EventCountry>

      <FirmName></FirmName>

      <Name></Name>

     <GeoCertified>< /GeoCertified/>

      <AuthorizedAgent>false</AuthorizedAgent>

      <EventCode>03</EventCode>

    </TrackDetail>

  </TrackInfo>

</TrackResponse>

 


 

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.

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.

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.

 

API Signature

Scheme

Host

Path

API

XML

https://

stg- secure.shippingapis.com

/ShippingAPI.dll

?API=PTSEmail

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSEmail

&XML=(see below)

 

Note: The “stg-secure.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at uspstechnicalsupport@mailps.custhelp.com

Request Description

Tag Name

Occurs

Description

Type

Validation

PTSEmailRequest

required once

API=PTSEmail

(group)

 

PTSEmailRequest / @USERID

required

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

string

minOccurs="1"

PTSEmailRequest / TrackId

required

Must be alphanumeric characters.

For example: 

<TrackId>EJ123456780US</TrackId>

string

minOccurs="1"

PTSEmailRequest / ClientIp

optional

User IP address. 

 

For Example:

<ClientIp>127.0.0.1</ClientIp>

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

Enter a notification request type from the choices available.

 

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

 

Enumerations no longer valid:

EC, EN, EB

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 once

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)

 

Sample Request and Response (Note: replace the userid & trackid with your values)

Test XML Request:

<PTSEmailRequest USERID="xxx">

    <TrackId>XXXXXXXXXX1</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

    <MpSuffix >9402</MpSuffix>

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

    <RequestType >AL</RequestType>

    <FirstName >John</FirstName>

    <LastName >Doe</LastName>

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

    <Email2></Email2>

    <Email3></Email3>

</PTSEmailRequest>

 

Test XML Response:

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

 

Test XML Request: Multiple Requests.

<PTSEmailRequest USERID="xxx">

    <TrackId>XXXXXXXXXX1</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

    <MpSuffix >9402</MpSuffix>

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

    <RequestType >AL</RequestType>

    <RequestType >FD</RequestType>

    <RequestType >UP</RequestType>

    <FirstName >John</FirstName>

    <LastName >Doe</LastName>

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

    <Email2></Email2>

    <Email3></Email3>

</PTSEmailRequest>

 


 

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. 

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.

API Signature

Scheme

Host

Path

API

XML

https://

stg-secure.shippingapis.com

/ShippingAPI.dll

?API=PTSPod

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSPod

&XML=(see below)

 

Note: The “stg-secure.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at uspstechnicalsupport@mailps.custhelp.com


 

Request Description

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

minOccurs="1"

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

 

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"

Sample Requests and Response (Note: replace the userid & trackid with your values)

Test XML Request:

<PTSPodRequest USERID="xxx">

    <TrackId>XXXXXXXXXX1</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

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

    <CustRegID>1234567890</CustRegID>

</PTSPodRequest>

 

Test XML Response:

<PTSPODRESULT>

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

    <ReturnCode>0</ReturnCode>

</PTSPODRESULT>


 

Return Receipt Electronic API

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

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.

 

API Signature

Scheme

Host

Path

API

XML

https://

stg-secure.shippingapis.com

/ShippingAPI.dll

?API=PTSRre

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSRre

&XML=(see below)

 

Note: The “stg-secure.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at uspstechnicalsupport@mailps.custhelp.com

Request Description

Tag Name

Occurs

Description

Type

Validation

PTSRreRequest

required once

API=PTSRre

(group)

 

PTSRreRequest / @USERID

required

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

string

 

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

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

 

For example: <Email1>cpapple@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’s associated to each user.

string

minOccurs="0"

PTSRreRequest

required

 

(alias)

 

 


 

Sample Request and Response (Note: replace the userid & trackid with your values)

Test XML Request:

<PTSRreRequest USERID="xxx">

    <TrackId>XXXXXXXXXX1</TrackId >

    <ClientIp>127.0.0.1</ClientIp>

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

 

Test XML Response:

<PTSRRERESULT>

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

   <ReturnCode>0</ReturnCode>

</PTSRRERESULT>

 

 

 

 

 

Track Proof of Delivery API

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. 

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

API Signature

Scheme

Host

Path

API

XML

https://

stg-secure.shippingapis.com

/ShippingAPI.dll

?API=PTSTPod

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PTSTPod

&XML=(see below)

 

Note: The “stg-secure.shippingapis.com” signature host is for testing purposes. If you experience any issues connecting to this test server, please contact our helpdesk at uspstechnicalsupport@mailps.custhelp.com

Request Description

Tag Name

Occurs

Description

Type

Validation

PTSTPodRequest

required once

 

(group)

 

PTSTPodRequest / @USERID

required

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

string

minOccurs="1"

PTSTPodRequest / Tra