Track & Confirm API
USPS Web Tools™
Application Programming Interface
User Guide
Version 4.6 (7/13/2023)
3.0 Package
Tracking “Fields” API
4.0 Track
and Confirm by Email API
6.0 Return
Receipt Electronic API
7.0 Track
Proof of Delivery API
1.0 Introduction
This
document contains a Reference Guide to the USPS Tracking/Delivery Confirmation Label APIs. See the Developer's
Guide to learn the administrative process for gaining
access to the Web Tools APIs as well as the basic mechanism for calling the
APIs and processing the results. The Developer’s Guide also contains
information on testing and troubleshooting.
Note: The
Request Parameter sections present the XML input tags for generating live
requests along with the restrictions on the values allowed. An error message
will be returned if an incorrect value is entered. Also, be aware of the maximum character
amounts allowed for some tags. If the user enters more than those amounts, an
error will not be generated. Web Tools will simply pass in the characters up to
the maximum amount allowed and disregard the rest. This is important since the
resulting value could prevent a correct response.
When
building the XML request, pay particular attention to the order and case for
tags. An error message will be returned if an incorrect value is entered.
Remember that all data and attribute values in this document are for
illustration purposes and are to be replaced by your actual values. For
instance, a line of sample code may be:
<TrackID>
EJ123456780US </TrackID>
In this instance, you will replace “EJ123456780US”
with the tracking ID for the package.
1.1 Before you get started:
For information on registering and getting started with Web Tools,
please refer to the Step-By-Step guide found on the Web Tools Technical
Documentation Page.
1.2 Tracking Service APIs
To obtain Package Tracking API
(API=TrackV2) access, users will need to follow the below steps.
1.
Register for Web Tools at https://registration.shippingapis.com/.
2. Obtain a valid registered mailer identification
number (MID). This is a 6 or 9-digit number assigned to a customer through the
USPS Business Customer Gateway (BCG). Please refer to the following links for
help.
o
https://gateway.usps.com/eAdmin/view/knowledge?securityId=MID
o
https://postalpro.usps.com/mailing/mailer-id
Important Note: Set
up of your MID must be completed prior to requesting access or your request
will be rejected. Please contact the NCSC-Delivery Confirmation (email: Delivery.confirmation@usps.gov;
phone: 1-877-264-9693, Option 1) for assistance.
3. Once the above steps are completed submit your Package Tracking access
request at: https://usps.force.com/emailus/s/web-tools-inquiry and provide your Web Tools user ID,
select ‘Tracking APIs’, select ‘Access for Tracking APIs’ and submit the
following information below in the “Additional Information” text box:
·
Web Tools User ID:
·
Mailer ID (MID):
·
Company Name:
·
Company Website:
·
Requester First and Last Name:
·
Requester Email:
·
Requester Phone number:
·
Mailing Address:
·
Mailing City:
·
Mailing State:
·
Mailing Zip Code:
·
Web Tools Registration Date:
·
API access requested: Package Tracking (API=TrackV2)
·
Anticipated volume: (daily, weekly, monthly, or annually)
·
Shipping done with USPS: Please describe.
·
Any additional information:
Four service APIs are offered in conjunction with “Revision=1” of the Package
Tracking “Fields” API: Track and Confirm by Email (PTSEmail), Proof of
Delivery (PTSPod), Track Proof of Delivery (PTSTPod), and Return Receipt Electronic (PTSRre). The response data from Track/Confirm Fields
request determines which services are available for a tracking ID. Each request
input to the Web Tools server for the tracking service APIs is limited to one
tracking ID. These APIs require additional permissions and in
order to gain access follow the
above steps.
2.0 Package Track API
2.1 Overview
The
Track/Confirm Web Tools API provides tracking status and delivery information
for USPS packages. The Track/Confirm API limits the data requested to
thirty-five (35) packages per transaction.
Note: The data returned by the Package Track Web Tools
API is intended for display only. The content or sequence of the String data
returned by the API may change. Consequently, if you desire to apply any kind
of logic against the tracking data, then you will need to use the Track/Confirm
fields.
2.1.1 API Signature Table
|
Host |
Path |
API |
XML |
|
|
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=TrackV2 |
&XML=(see below) |
2.2 Request Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
TrackRequest |
Required |
API=TrackV2 |
(Alias) |
|
|
TrackRequest
/ USERID |
Required |
This attribute specifies your Web Tools user ID. See the Developer's Guide for information on obtaining your
USERID. For Example: USERID="XXXXXXX" |
NMTOKEN |
|
|
TrackRequest
/ PASSWORD |
Optional |
This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. For Example: PASSWORD="XXXXXXX" |
NMTOKEN |
|
|
TrackRequest / TrackID |
Required |
Must be
alphanumeric characters. For
example: <TrackID
ID="EJ123456780US"> </TrackID> |
String |
minOccurs="1" |
2.2.1 Sample Request
|
<TrackRequest USERID="XXXXXXXXX"
PASSWORD=""> <TrackID ID="XXXXXXXXXXX1"></TrackID> <TrackID ID="XXXXXXXXXXX2"></TrackID> </TrackRequest> |
2.3 Response Descriptions
|
Occurs |
Descriptions |
Type |
Validation |
|
|
TrackResponse |
Required |
|
|
|
|
Required max 10 |
|
(Group) |
|
|
|
TrackResponse / TrackInfo ID |
Required |
Tracking
ID |
Token |
|
|
TrackResponse / TrackInfo / DeliveryNotificationDate |
Optional |
|
String |
minOccurs="0" |
|
TrackResponse / TrackInfo / ExpectedDeliveryDate |
Optional |
Expected
delivery date |
String |
minOccurs="0" |
|
TrackResponse / TrackInfo / ExpectedDeliveryTime |
Optional |
Expected
Delivery Time |
String |
minOccurs="0" |
|
TrackResponse / TrackInfo / GuaranteedDeliveryDate |
Optional |
Guaranteed
Delivery Date – Global Express Mail only: certain countries provide a
guarantee delivery For
Example: April 15, 2020 Or 3 Business
Days |
String |
minOccurs="0" |
|
TrackResponse / TrackInfo / TrackSummary |
Optional |
Summary of
the status of the shipment, ie
In-Transit, Delivered, etc. For
example: February 5 7:28 pm ENROUTE 33699 |
String |
|
|
TrackResponse / TrackInfo / TrackDetail |
Optional |
Scan
statuses from points in transit. |
String |
minOccurs="0" |
|
TrackResponse |
Required |
|
(Alias) |
|
2.3.1 Sample Response
Response: Package Track
<TrackResponse>
<TrackInfo ID="XXXXXXXXXXX1">
<TrackSummary> Your item was delivered
at 6:50 am on February 6 in BARTOW FL 33830.</TrackSummary>
<TrackDetail>February 6 6:49 am NOTICE
LEFT BARTOW FL 33830</TrackDetail>
<TrackDetail>February 6 6:48 am ARRIVAL
AT UNIT BARTOW FL 33830</TrackDetail>
<TrackDetail>February 6 3:49 am ARRIVAL
AT UNIT LAKELAND FL 33805</TrackDetail>
<TrackDetail>February 5 7:28 pm ENROUTE
33699</TrackDetail>
<TrackDetail>February 5 7:18 pm ACCEPT
OR PICKUP 33699</TrackDetail>
</TrackInfo>
<TrackInfo ID="XXXXXXXXXXX2">
<TrackSummary There is no record of that
mail item. If it was mailed recently, It may not yet
be tracked. Please try again later. </TrackSummary>
</TrackResponse>
3.0 Package Tracking “Fields” API
3.1 Overview
The Package Tracking “Fields” API is similar to the Package Track API except for the request
fields, API name, and the return information. Data returned still contains the
detail and summary information, but this information is broken down into fields
instead of having only one line of text. Up to 10 tracking IDs may be contained
in each API request to the Web Tools server.
3.1.1 API Signature
|
Scheme |
Host |
Path |
API |
XML |
|
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=TrackV2 |
&XML=(see below) |
3.2 Request Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
TrackFieldRequest |
Required |
API=TrackV2 |
(Alias) |
|
|
TrackFieldRequest / USERID |
Required |
This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID. For Example: USERID="XXXXXXX" |
NMTOKEN |
|
|
TrackFieldRequest / PASSWORD |
Optional |
This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password. For Example: PASSWORD="XXXXXXX" |
NMTOKEN |
|
|
TrackFieldRequest / Revision |
Required |
This is for versioning of the API's and
for triggering response tags for future versions. In this API use a value of
1 to return all available response tags and trigger new functionality. For example: <Revision>1</Revision> |
minOccurs="0" |
|
|
TrackFieldRequest / ClientIp |
Optional |
User’s IP address. ClientIP is required
when <Revision>=1 For example: <ClientIp>137.0.0.1</ClientIp> Note: Web Tools will always collect the
physical IP address from the system generating the API call. This will be
passed on the backend to a separate internal package tracking system. |
String |
minOccurs="0" |
|
TrackFieldRequest / SourceId |
Required |
External integrators should pass company
name. SourceID is required when <Revision>=1. For example: <SourceId>XYZ
Corp</SourceId> |
String |
minOccurs="0" Pattern="[0-9]{5}" |
|
TrackFieldRequest / TrackID |
Required |
Package Tracking ID. Must be alphanumeric characters. For example: <TrackID
ID="EJ123456780US"></TrackID> |
String |
minOccurs="1" |
|
TrackFieldRequest / TrackID / DestinationZipCode |
Optional |
5-digit destination ZIP
Code. For example:
<DestinationZipCode>12345</DestinationZipCode> |
String |
minOccurs="0" |
|
TrackFieldRequest / TrackID / MailingDate |
Optional |
Mailing date of package. Format:
YYYY-MM-DD For example: <MailingDate>2010-01-01</MailingDate> |
String |
minOccurs="0" |
|
TrackFieldRequest |
Required |
API=TrackV2 |
(Alias) |
|
3.2.1 Sample Request
|
Request: Track and Confirm <TrackFieldRequest USERID="XXXXXXXXX"
PASSWORD=""> <Revision>1</Revision> <ClientIp>122.3.3</ClientIp> <SourceId>XYZ Corp</SourceId> <TrackID ID="xxxxxxxxxxxxxxxxxxx"/> </TrackFieldRequest> |
3.2 Response Descriptions
3.3.2 Sample Response
|
Response: Package Tracking “Fields” <TrackResponse> <TrackInfo ID=" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ">
<GuaranteedDeliveryDate>June 24,
2022</GuaranteedDeliveryDate>
<TrackSummary>
<EventTime>9:00 am</EventTime>
<EventDate>June 22, 2022</EventDate>
<Event>Delivered, To Agent</Event>
<EventCity>AMARILLO</EventCity>
<EventState>TX</EventState>
<EventZIPCode>79109</EventZIPCode>
<EventCountry/> <FirmName/>
<Name>RXXXXXX XXXXXXX</Name>
<AuthorizedAgent>false</AuthorizedAgent>
<DeliveryAttributeCode/>
<GMT>14:00:00</GMT>
<GMTOffset>-05:00</GMTOffset>
</TrackSummary> <TrackDetail>
<EventTime/>
<EventDate>June 22, 2022</EventDate>
<Event>USPS expects item for mailing (SSK)</Event>
<EventCity>LAUREL</EventCity>
<EventState>MD</EventState>
<EventZIPCode>20707</EventZIPCode>
<EventCountry/>
<FirmName/>
<Name/>
<AuthorizedAgent>false</AuthorizedAgent>
<GMT/>
<GMTOffset/>
</TrackDetail> </TrackInfo> </TrackResponse> Response (Revision = 1): Package Tracking
“Fields” <TrackResponse> <TrackInfo ID=" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
">
<Class>Priority Mail Express 2-Day<SUP>&reg;</SUP></Class>
<ClassOfMailCode>EX</ClassOfMailCode>
<DestinationCity>AMARILLO</DestinationCity>
<DestinationState>TX</DestinationState>
<DestinationZip>79109</DestinationZip>
<EmailEnabled>true</EmailEnabled>
<GuaranteedDeliveryDate>June 24,
2022</GuaranteedDeliveryDate>
<GuaranteedDeliveryTime>6:00pm</GuaranteedDeliveryTime>
<GuaranteedDetails>Money Back
Guarantee</GuaranteedDetails>
<KahalaIndicator>false</KahalaIndicator>
<MailTypeCode>DM</MailTypeCode>
<MPDATE>2022-06-24 11:30:26.000000</MPDATE>
<MPSUFFIX>XXXXXXX</MPSUFFIX>
<OriginCity>LAUREL</OriginCity>
<OriginState>MD</OriginState>
<OriginZip>20707</OriginZip>
<PodEnabled>true</PodEnabled>
<TPodEnabled>false</TPodEnabled>
<RestoreEnabled>false</RestoreEnabled>
<RramEnabled>false</RramEnabled>
<RreEnabled>false</RreEnabled>
<Service>Signature Confirmation<SUP>&#153;</SUP></Service>
<Service>Up to $100 insurance included</Service>
<ServiceTypeCode>889</ServiceTypeCode>
<Status>Delivered, To Agent</Status>
<StatusCategory>Delivered</StatusCategory>
<StatusSummary>Your item has been
delivered to an agent at 9:00 am on June 22, 2022 in
AMARILLO, TX 79109. The item was signed for by R XXXXXXX.</StatusSummary>
<TABLECODE>T</TABLECODE>
<TrackSummary>
<EventTime>9:00 am</EventTime>
<EventDate>June 22, 2022</EventDate>
<Event>Delivered, To Agent</Event>
<EventCity>AMARILLO</EventCity>
<EventState>TX</EventState>
<EventZIPCode>79109</EventZIPCode>
<EventCountry/>
<FirmName/>
<Name>RXXXXXX XXXXXXX</Name>
<AuthorizedAgent>false</AuthorizedAgent>
<EventCode>01</EventCode>
<DeliveryAttributeCode/>
<GMT>14:00:00</GMT>
<GMTOffset>-05:00</GMTOffset>
</TrackSummary>
<TrackDetail>
<EventTime/>
<EventDate>June 22, 2022</EventDate>
<Event>USPS expects item for mailing (SSK)</Event>
<EventCity>LAUREL</EventCity>
<EventState>MD</EventState>
<EventZIPCode>20707</EventZIPCode> <EventCountry/>
<FirmName/>
<Name/>
<AuthorizedAgent>false</AuthorizedAgent>
<EventCode>03</EventCode>
<GMT/>
<GMTOffset/>
</TrackDetail> </TrackInfo> </TrackResponse> Error
Response: <TrackResponse> <TrackInfo ID="XXXXXXXXXXXXXXXXXX"> <Error> <Number>-2147219283</Number> <Description>A
status update is not yet available on your Priority Mail
Express<SUP>®</SUP> package. It will be available when
the shipper provides an update or the package is
delivered to USPS. Check back soon. Sign up for Informed
Delivery<SUP>®</SUP> to receive notifications for
packages addressed to you.</Description> <HelpFile/> <HelpContext/> </Error> </TrackInfo> |
4.0 Track and Confirm by Email API
4.1 Overview
The Track and Confirm by Email API allows the
customer to submit their email address to be notified of current or future
tracking activity. When you request access for this API, please identify your
anticipated API volume, mailer ID and how you will be utilizing this API. A
mailer identification number (MID) is a 6 or 9-digit number assigned to a
customer through the USPS Business Customer Gateway (BCG). Please refer to the
following links for help:
- https://gateway.usps.com/eAdmin/view/knowledge?securityId=MID
- https://postalpro.usps.com/mailing/mailer-id
4.1.1 API Signature
|
Scheme |
Host |
Path |
API |
XML |
|
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=PTSEmail |
&XML=(see below) |
4.2 Request Descriptions
|
Tag
Name |
Occurs |
Descriptions |
Type |
Validation |
||||||||||||||||
|
Required |
API=PTSEmail. |
(Alias) |
|
|||||||||||||||||
|
PTSEmailRequest
/ USERID |
Required |
This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID. For Example: USERID="XXXXXXX" |
NMTOKEN |
|
||||||||||||||||
|
PTSEmailRequest
/ PASSWORD |
Optional |
This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password. For Example: PASSWORD="XXXXXXX" |
NMTOKEN |
|
||||||||||||||||
|
PTSEmailRequest / TrackId |
Required |
Must be alphanumeric characters. For example: <TrackId>EJ123456780US</TrackId> |
String |
minOccurs="1" |
||||||||||||||||
|
PTSEmailRequest /
ClientIp |
Optional |
User IP address.
For example:
<ClientIp>127.0.0.0</ClientIp> |
String |
minOccurs="0" |
||||||||||||||||
|
PTSEmailRequest / SourceId |
Optional |
Internal User Identification. For example: <SourceId>XYZ
Corp</SourceId> |
String |
minOccurs="0" |
||||||||||||||||
|
PTSEmailRequest / MpSuffix |
Required |
MPSUFFIX value located in
Track/Confirm Fields API response data. Unique to each TrackID. For example: <MpSuffix>9402</MpSuffix> |
Integer |
minOccurs="1" |
||||||||||||||||
|
PTSEmailRequest / MpDate |
Required |
MPDATE value located in Track/Confirm Fields API
response data. Unique to each TrackId. For example: <MpDate>2009-07-02
00:42:23.35744</MpDate> |
String |
minOccurs="1" |
||||||||||||||||
|
PTSEmailRequest / RequestType |
Required once,repeating
up to 5 times |
Enter a notification request type from the
choices available.
For example: <RequestType>ED</RequestType> |
String |
minOccurs="1" Enumerations= ·
AL ·
FD ·
ED ·
TD ·
UP ·
FS ·
OA |
||||||||||||||||
|
PTSEmailRequest /
FirstName |
Optional |
Recipient First Name. For example:
<FirstName>John</FirstName> |
String |
minOccurs="0" |
||||||||||||||||
|
PTSEmailRequest /
LastName |
Optional |
Recipient Last Name. For example: <LastName>Doe</LastName> |
String |
minOccurs="0" |
||||||||||||||||
|
PTSEmailRequest / Email1 |
Required |
Complete valid e-mail address is Required if tag
is used. For example:
<Email1>cpapple@email.com</Email1> |
String |
minOccurs="1" |
||||||||||||||||
|
PTSEmailRequest / Email2 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
||||||||||||||||
|
PTSEmailRequest / Email3 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
||||||||||||||||
|
PTSEmailRequest |
Required once |
API=PTSEmail |
(Alias) |
|
4.2.1 Sample Request
|
Request: PTSEmail <PTSEmailRequest USERID="XXXXXXXXX" PASSWORD=""> <TrackId>XXXXXXXXXXX</TrackId
> <ClientIp>127.2.0.1</ClientIp> <SourceId>XYZ Corp</SourceId> <MpSuffix >9402</MpSuffix> <MpDate >2009-07-02 00:42:23.35744</MpDate> <RequestType>EN</RequestType> <FirstName>John</FirstName> <LastName
>Doe</LastName> <Email1>test@email.com</Email1> <Email2></Email2> <Email3></Email3> </PTSEmailRequest> |
4.3 Response Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
PTSEmailResponse |
Required |
|
(Alias) |
|
|
PTSEmailResponse / ResultText |
Required |
Status message. |
String |
|
|
PTSEmailRequest / ReturnCode |
Required |
Return code. |
Integer |
|
|
PTSEmailResponse |
Required |
|
(Alias) |
|
4.3.1 Sample Response
|
Response: PTSEmail <PTSEMAILRESULT> <ResultText>Your
request for all activity to-date will be processed within four hours. Any
future activity will be processed whenever there is new delivery related
event activity.</ResultText> <ReturnCode>0</ReturnCode> </PTSEMAILRESULT> |
5.0 Proof of Delivery API
5.1 Overview
Proof of Delivery is a letter that
includes the recipient's name and a copy of their signature. The Proof of
Delivery API allows the customer to request proof of delivery notification via
email. When you request access for this API, please identify your anticipated
API volume, mailer ID and how you will be utilizing this API. A mailer
identification number (MID) is a 6 or 9-digit number assigned to a customer
through the USPS Business Customer Gateway (BCG). Please refer to the following
links for help:
- https://gateway.usps.com/eAdmin/view/knowledge?securityId=MID
- https://postalpro.usps.com/mailing/mailer-id
5.1.1 API Signature
|
Scheme |
Host |
Path |
API |
XML |
|
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=PTSPod |
&XML=(see below) |
5.2 Request Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
PTSPodRequest |
Required once |
|
(Alias) |
|
|
PTSPodRequest /
USERID |
Required |
This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID. For Example: USERID="XXXXXXX" |
NMTOKEN |
|
|
PTSPodRequest /
PASSWORD |
Optional |
This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password. For Example: PASSWORD="XXXXXXX" |
NMTOKEN |
|
|
PTSPodRequest / TrackId |
Required |
Must be alphanumeric characters. For example:
<TrackId>EJ123456780US</TrackId> |
String |
minOccurs="1" |
|
PTSPodRequest /
ClientIp |
Optional |
User IP address.
For example: <ClientIp>127.0.0.1</ClientIp> |
String |
minOccurs="0" |
|
PTSPodRequest / SourceId |
Optional |
Internal User Identification. For example: <SourceId>XYZ
Corp</SourceId> |
String |
minOccurs="0" |
|
PTSPodRequest / MpSuffix |
Required |
MPSUFFIX value located in Track/Confirm Fields
API response data. Unique to each TrackId. For example: <MpSuffix>9402</MpSuffix> |
integer |
minOccurs="1" |
|
PTSPodRequest / MpDate |
Required |
MPDATE value located in Track/Confirm Fields API
response data. Unique to each TrackID. For example: <MpDate>2009-07-02
00:42:23.35744</MpDate> |
String |
minOccurs="1" |
|
PTSPodRequest / RequestType |
Required |
Enter a notification request type from the
choices available. For example: <RequestType>Email</RequestType> |
String |
minOccurs="1" |
|
PTSPodRequest /
FirstName |
Required |
Recipient First Name. For example:
<FirstName>John</FirstName> |
String |
minOccurs="1" |
|
PTSPodRequest /
LastName |
Required |
Recipient Last Name. For example: <LastName>Doe</LastName> |
String |
minOccurs="1" |
|
PTSPodRequest / Email1 |
Optional |
Required when PTSPodRequest[RequestType=’Email’]. Complete valid e-mail address is Required if tag
is used. For example:
<Email1>cpapple@email.com</Email1> |
String |
minOccurs="0" |
|
PTSPodRequest / Email2 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
|
PTSPodRequest / Email3 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
|
PTSPodRequest / FaxNumber |
Optional |
Fax Number. |
String |
minOccurs="0" |
|
PTSPodRequest /
AddressLine1 |
Optional |
Address Line 1. |
String |
minOccurs="0" |
|
PTSPodRequest /
AddressLine2 |
Optional |
Address Line 2. |
String |
minOccurs="0" |
|
PTSPodRequest / City |
Optional |
City |
String |
minOccurs="0" |
|
PTSPodRequest / State |
Optional |
State |
String |
minOccurs="0" |
|
PTSPodRequest / Zip |
Optional |
Zip |
String |
minOccurs="0" |
|
PTSPodRequest / VerifyAddress |
Optional |
Indicates whether or not
address should be validated. |
Boolean |
minOccurs="0" |
|
PTSPodRequest / TableCode |
Required |
TableCode value
located in Track/Confirm Fields API response data. Unique to each TrackID. For example: <TableCode>T</TableCode> |
String |
minOccurs="1" |
|
PTSPodRequest / CustRegID |
Optional |
Unique 10-byte numeric value that’s associated to
each user. |
String |
minOccurs="0" |
|
PTSPodRequest |
Required once |
|
(Alias) |
|
5.2.1 Sample Request
|
Request: PTSPod <PTSPodRequest USERID="XXXXXXXXX"
PASSWORD=""> <TrackId>XXXXXXXXXXX</TrackId
> <ClientIp>127.0.0.1</ClientIp> <SourceId>XXXXXX</SourceId> <MpSuffix>9402</MpSuffix> <MpDate>2009-07-02 00:42:23.35744</MpDate> <RequestType>Email</RequestType> <FirstName>John</FirstName> <LastName>Doe</LastName> <Email1>test@email.com
</Email1> <Email2></Email2> <Email3></Email3> <TableCode>T</TableCode> <CustRegID>1234567890</CustRegID> </PTSPodRequest> |
5.3 Response Descriptions
|
Tag
Name |
Occurs |
Descriptions |
Type |
Validation |
|
PTSPODResult |
Required |
|
(Alias) |
|
|
PTSPODResponse / ResultText |
Required |
Status message. |
String |
|
|
PTSPODRequest / ReturnCode |
Required |
Return code. |
Integer |
|
|
PTSPODResult |
Required |
|
(Alias) |
|
5.3.1 Sample Response
|
Response:
PTSPOD <PTSPODRESULT> <ResultText>Your Proof of Delivery record is complete
and will be processed shortly.</ResultText> <ReturnCode>0</ReturnCode> </PTSPODRESULT> |
6.0 Return Receipt Electronic API
6.1 Overview
- https://gateway.usps.com/eAdmin/view/knowledge?securityId=MID
- https://postalpro.usps.com/mailing/mailer-id
6.1.1 API Signature
|
Scheme |
Host |
Path |
API |
XML |
|
|
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=PTSRre |
&XML=(see below) |
|
6.2 Request Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
PTSRreRequest |
Required |
API=PTSRre |
(Alias) |
|
|
PTSRreRequest /
USERID |
Required |
This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID. For Example: USERID="XXXXXXX" |
NMTOKEN |
|
|
PTSRreRequest /
PASSWORD |
Optional |
This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password. For Example: PASSWORD="XXXXXXX" |
NMTOKEN |
|
|
PTSRreRequest / TrackId |
Required |
Must be alphanumeric characters. For example:
<TrackId>EJ123456780US</TrackId> |
String |
minOccurs="1" |
|
PTSRreRequest /
ClientIp |
Optional |
User IP address.
For example: <ClientIp>127.0.0.1</ClientIp> |
String |
minOccurs="0" |
|
PTSRreRequest / SourceId |
Optional |
Internal User Identification. For example: <SourceId>XYZ
Corp</SourceId> |
String |
minOccurs="0" |
|
PTSRreRequest / MpSuffix |
Required |
MPSUFFIX value located in Track/Confirm Fields
API response data. Unique to each TrackId. For example: <MpSuffix>9402</MpSuffix> |
integer |
minOccurs="1" |
|
PTSRreRequest / MpDate |
Required |
MPDATE value located in Track/Confirm Fields API
response data. Unique to each TrackID. For example: <MpDate>2009-07-02
00:42:23.35744</MpDate> |
String |
minOccurs="1" |
|
PTSRreRequest /
FirstName |
Required |
Recipient First Name. For example:
<FirstName>John</FirstName> |
String |
minOccurs="1" |
|
PTSRreRequest /
LastName |
Required |
Recipient Last Name. For example: <LastName>Doe</LastName> |
String |
minOccurs="1" |
|
PTSRreRequest / Email1 |
Required |
Complete valid e-mail address is Required if tag
is used. For example: <Email1>cgpapple@email.com</Email1> |
String |
minOccurs="1" |
|
PTSRreRequest / Email2 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
|
PTSRreRequest / Email3 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
|
PTSRreRequest / TableCode |
Required |
TableCode value
located in Track/Confirm Fields API response data. Unique to each TrackID. For example: <TableCode>T</TableCode> |
String |
minOccurs="1" |
|
PTSRreRequest / CustRegID |
Optional |
Unique 10-byte numeric value that is associated
to each user. |
String |
minOccurs="0" |
|
PTSRreRequest |
Required |
|
(Alias) |
|
6.2.1 Sample Request
|
Request: PTSRre <PTSRreRequest USERID="XXXXXXXXX"
PASSWORD=""> <TrackId>XXXXXXXXXXX</TrackId > <ClientIp>127.0.0.1</ClientIp> <SourceId>XYZ
Corp</SourceId> <MpSuffix>9402</MpSuffix> <MpDate>2009-07-02
00:42:23.35744</MpDate> <FirstName>John</FirstName> <LastName>Doe</LastName> <Email1>cpapple@email.com</Email1> <Email2></Email2> <Email3></Email3> <TableCode>T</TableCode> <CustRegID>1234567890</CustRegID> </PTSRreRequest> |
6.3 Response Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
PTSRreResult |
Required |
|
(Alias) |
|
|
PTSRreResponse / ResultText |
Required |
Status message. |
String |
|
|
PTSRreRequest / ReturnCode |
Required |
Return code. |
Integer |
|
|
PTSRreResult |
Required |
|
(Alias) |
|
6.3.1 Sample Response
|
Response: PTSRre <PTSRRERESULT> <ResultText>Your
Proof of Delivery record is complete and will be processed shortly</ResultText> <ReturnCode>0</ReturnCode> </PTSRRERESULT> |
7.0 Track Proof of Delivery API
7.1 Overview
Track Proof of Delivery is a letter
that includes the recipient's name and a copy of their signature. The Track
Proof of Delivery API allows the customer to request proof of delivery
notification via email. When you request access for this API, please identify
your anticipated API volume, mailer ID and how you will be utilizing this API.
A mailer identification number (MID) is a 6 or 9-digit number assigned to a
customer through the USPS Business Customer Gateway (BCG). Please refer to the
following links for help:
- https://gateway.usps.com/eAdmin/view/knowledge?securityId=MID
- https://postalpro.usps.com/mailing/mailer-id
7.1.1 API Signature
|
Scheme |
Host |
Path |
API |
XML |
|
https:// |
secure.shippingapis.com |
/ShippingAPI.dll? |
API=PTSTPod |
&XML=(see below) |
7.2 Request Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
PTSTpodRequest |
Required |
|
(Alias) |
|
|
PTSTpodRequest / USERID |
Required |
This attribute specifies your Web Tools user ID. See the Developer’s Guide for information on obtaining your USERID. For Example: USERID="XXXXXXX" |
NMTOKEN |
|
|
PTSTpodRequest / PASSWORD |
Optional |
This attribute specifies your Web Tools password. See the Developer’s Guide for information on your Password. For Example: PASSWORD="XXXXXXX" |
NMTOKEN |
|
|
PTSTpodRequest / TrackId |
Required |
Must be alphanumeric characters. For example:
<TrackId>EJ123456780US</TrackId> |
String |
minOccurs="1" |
|
PTSTpodRequest / MpSuffix |
Required |
MPSUFFIX value located in Track/Confirm Fields
API response data. Unique to each TrackId. For example: <MpSuffix>9402</MpSuffix> |
integer |
minOccurs="1" |
|
PTSTpodRequest / MpDate |
Required |
MPDATE value located in Track/Confirm Fields API
response data. Unique to each TrackID. For example: <MpDate>2009-07-02
00:42:23.35744</MpDate> |
String |
minOccurs="1" |
|
PTSTpodRequest / RequestType |
Required |
Enter a notification request type from the
choices available. For example: <RequestType>Email</RequestType> |
String |
minOccurs="1" |
|
PTSTpodRequest /
FirstName |
Required |
Recipient First Name. For example:
<FirstName>John</FirstName> |
String |
minOccurs="1" |
|
PTSTpodRequest /
LastName |
Required |
Recipient Last Name. For example: <LastName>Doe</LastName> |
String |
minOccurs="1" |
|
PTSTpodRequest / Email1 |
Optional |
Required when PTSTpodRequest[RequestType=’Email’]. Complete valid e-mail address is Required if tag
is used. For example:
<Email1>cpapplee@email.com</Email1> |
String |
minOccurs="0" |
|
PTSTpodRequest / Email2 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
|
PTSTpodRequest / Email3 |
Optional |
Complete valid e-mail address is Required if tag
is used. |
String |
minOccurs="0" |
|
PTSTpodRequest / CustRegID |
Required |
Unique 10-byte numeric value that’s associated to
each user. |
String |
minOccurs="0" |
|
PTSTpodRequest / TableCode |
Required |
TableCode value
located in Track/Confirm Fields API response data. Unique to each TrackID. For example: <TableCode>T</TableCode> |
String |
minOccurs="1" |
|
PTSTpodRequest /
ClientIp |
Optional |
User IP address. For example: <ClientIp>133.2.1.1</ClientIp> |
String |
minOccurs="0" |
|
PTSTpodRequest / SourceId |
Optional |
Internal User Identification. Required when TrackFieldRequest[Revision=’1’]. For example: <SourceID>XYZ
Corp</SourceID> |
String |
minOccurs="0" |
|
PTSTpodRequest |
Required |
|
(alias) |
|
7.2.1 Sample Request
|
Request: PTSTPod <PTSTpodRequest USERID="XXXXXXXXX"
PASSWORD=""> <TrackId>XXXXXXXXXXX</TrackId > <MpSuffix>9402</MpSuffix> <MpDate>2009-07-02
00:42:23.35744</MpDate> <RequestType>Email</RequestType> <FirstName>John</FirstName> <LastName>Doe</LastName> <Email1>cpapple@email.com </Email1> <Email2></Email2> <Email3></Email3> <CustRegID>1234567890</CustRegID> <TableCode>T</TableCode> <ClientIp>127.0.0.1</ClientIp> <SourceId>XXXXX</SourceId> </PTSTpodRequest> |
7.3 Response Descriptions
|
Tag Name |
Occurs |
Descriptions |
Type |
Validation |
|
PTSTPODResult |
Required |
|
(Alias) |
|
|
PTSTPODResponse / ResultText |
Required |
Status message. |
String |
|
|
PTSTpodRequest / ReturnCode |
Required |
Return code. |
Integer |
|
|
PTSTPODResult |
Required |
|
(Alias) |
|
7.3.1 Sample Response
|
Response: PTSTPod <PTSTPODRESULT> <ResultText>Your
Proof of Delivery record is complete and will be processed shortly.</ResultText> <ReturnCode>0</ReturnCode> </PTSTPODRESULT> |