USPS Web Tools API (1.0)

This site is an open source effort to improve the experience for developers utilizing the USPS Web Tools APIs.

Documentation is generated using Redoc and an OpenAPI 3.0 spec created from the USPS official documentation (PDF format).

We have corrected errors and made UX improvements but welcome your feedback on how to improve this site in the future. Contact us at lob-openapi@lob.com

Who is Lob?

Lob offers Direct Mail APIs Designed for Developers.

Transform outdated, manual print & mail processes with Lob’s easy-to-integrate APIs. Trigger on-demand postcards, letters, and checks directly from your CRM or custom applications.

Improve your mail deliverability by adding address autocomplete on the front-end, and correct, standardize, and cleanse address data for assured delivery across 240+ countries and territories.

Meet compliance requirements by deploying webhooks to automatically track production and delivery for each piece of mail. Send HIPAA-compliant mailings that properly protect healthcare data and report on real-time and historic mail statuses for compliance audits.

Web Tools Authentication

USPS Web Tools API are accessible using your Web Tools User ID. To authenticate a request add the USERID attribute to the outermost XML element and set the value equal to your Web Tools User ID.

For example, <AddressValidateRequest USERID="{WEB_TOOLS_USER_NAME}">

Register on the USPS Web Tools API Portal for your Web Tools ID.

You'll receive an email with your Web Tools username (This is your USERID)

USPS official Developers Guide - PDF format.

Note: USPS Web Tools API does not follow standard OAuth, OpenID or Basic Authentication patterns. For this reason, securitySchemes have been omitted in the OpenAPI specification used to generate this documentation.

Important Notice: User ID

The Web Tools User ID provided is for you and your company to use when requesting data via the Internet from the U.S. Postal Service API servers. As per the Terms and Conditions of Use Agreement you agreed to during the Web Tools registration process, you are responsible to maintain the confidentiality of your User ID as specified. You may not package any APIs with your User ID for resale or distribution to others. The U.S. Postal Service does not prohibit the reuse and/or distribution of the API documentation (User's Guide) with sample code in order to generate awareness, encourage use or provide ease-of-use to customers or affiliates.

Warning - If the U.S. Postal Service discovers use of the same User ID from more than one web site, all users will be subject to loss of access to the USPS production server and/or termination of the licenses granted under the Terms and Conditions of Use.

Postman

We've created a Postman public workspace for developers to explore the USPS Web Tools APIs. You will need your own Web Tools UserID to use this collection. See Authentication

Address Verification

Domestic Mail Service

Track & Confirm Package

Address Verification APIs

The Address Validation APIs can be used in conjunction with USPS SHIPPING OR MAILING SERVICES ONLY. The Address API must only be used on an individual transactional basis, i.e. not batch processing or cleansing of a database, but as a customer enters the information into a form on a website. Failure to comply with these terms and conditions can result in termination of USPS API access without prior notice.

Address

The Address/Standardization "Verify" API, which corrects errors in street addresses, including abbreviations and missing information, and supplies ZIP Codes and ZIP Codes + 4. The Verify API supports up to five lookups per transaction. By eliminating address errors, you will improve overall package delivery service.

Verify a US address

query Parameters

API required	string Default: "Verify" This query parameter defines the resource you are accessing. For address verification your API query param value must equal `Verify`.
required	object (AddressValidateRequest) This query parameter defines the XML payload and can not be passed in the body <AddressValidateRequest USERID="XXXXXX"> <Revision>1</Revision> <Address> <Address1>Suite 6100</Address1> <Address2>185 Berry St</Address2> <City>San Francisco</City> <State>CA</State> <Zip5>94556</Zip5> <Zip4></Zip4> </Address> </AddressValidateRequest>

Responses

Response Schema: text/xml

object

FirmName	string Example: "XYZ Corp" a company name
Address1	string Example: "Suite 6100" Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE
Address2	string Example: "185 Berry St" Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
Address2Abbreviation	string Address line 2 abbreviation. To return abbreviations you must set =1
City	string <= 15 characters Example: "San Francisco" City name of the destination address.
CityAbbreviation	string Abbreviated city name of the destination address. To return abbreviations you must set =1
State	string <= 2 characters Example: "CA" Two-character state code of the destination address.
Zip5	string Example: "94556" Destination 5-digit ZIP Code. Numeric values (0-9) only. If International, all zeroes.
Zip4	string Destination ZIP+4 Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
Urbanization	string <= 28 characters For Puerto Rico addresses only.
DeliveryPoint	string
CarrierRoute	string Carrier Route code.
Footnotes	string Enum: "A" "B" "C" "D" "E" "F" "G" "H" "I" "J" "K" "L" "LI" "M" "N" … 12 more
DPVConfirmation	string Enum: "Y" "D" "S" "N" The DPV Confirmation Indicator is the primary method used by the USPS to determine whether an address was considered deliverable or undeliverable.
DPVCMRA	string Enum: "Y" "N" CMRA Indicates a private business that acts as a mailreceiving agent for specific clients. “Y” Address was found in the CMRA table. “N” Address was not found in the CMRA table. Blank Address no
DPVFootnotes	string Enum: "AA" "A1" "BB" "CC" "N1" "M1" "M3" "P1" "P3" "F1" "G1" "U1" DPV® Standardized Footnotes - EZ24x7Plus and Mail*STAR are required to express DPV results using USPS standard two character footnotes.
Business	string Enum: "Y" "N" Indicates whether address is a business or not
CentralDeliveryPoint	string Enum: "Y" "N" Central Delivery is for all business office buildings, office complexes, and/or industrial/professional parks. This may include call windows, horizontal locked mail receptacles, cluster box units.
Vacant	string Enum: "Y" "N" Is the location not occupied.
ReturnText	string data validation error message
	object

Response samples

200

Content type

text/xml

<AddressValidateResponse> <Address> <Address1>STE 6100</Address1> <Address2>185 BERRY ST</Address2> <City>SAN FRANCISCO</City> <State>CA</State> <Zip5>94107</Zip5> <Zip4>1741</Zip4> <DeliveryPoint>25</DeliveryPoint> <CarrierRoute>C001</CarrierRoute> <Footnotes>AN</Footnotes> <DPVConfirmation>Y</DPVConfirmation> <DPVCMRA>N</DPVCMRA> <DPVFootnotes>AABB</DPVFootnotes> <Business>Y</Business> <CentralDeliveryPoint>N</CentralDeliveryPoint> <Vacant>N</Vacant> </Address> </AddressValidateResponse>

City & State

City/State Lookup API returns the city and state corresponding to the given ZIP Code. The CityStateLookup API processes up to five lookups per request.

Lookup City & State

query Parameters

API required	string Default: "CityStateLookup" This query parameter defines the resource you are accessing. For city & state lookup your API query param value must equal `CityStateLookup`.
required	object (CityStateLookupRequest) This query parameter defines the XML payload and it can not be passed in the body <CityStateLookupRequest USERID="XXXXXX"> <ZipCode> <Zip5>94107</Zip5> </ZipCode> </CityStateLookupRequest>

Responses

Response Schema: text/xml

object

City	string <= 15 characters Example: "San Francisco" City name of the destination address.
State	string <= 2 characters Example: "CA" Two-character state code of the destination address.
Zip5	string Example: "94556" Destination 5-digit ZIP Code. Numeric values (0-9) only. If International, all zeroes.
ReturnText	string Example: "Default address - The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address."
	object

Response samples

200

Content type

text/xml

<CityStateLookupResponse> <ZipCode> <Zip5>94556</Zip5> <City>MORAGA</City> <State>CA</State> </ZipCode> </CityStateLookupResponse>

ZIP Code

The ZipCodeLookup API, which returns the ZIP Code and ZIP Code + 4 corresponding to the given address, city, and state (use USPS state abbreviations). The ZipCodeLookup API processes up to five lookups per request.

Lookup a ZIP Code

query Parameters

API required	string Default: "ZipCodeLookup" This query parameter defines the resource you are accessing. For ZIP Code lookup your API query param value must equal `ZipCodeLookup`.
required	object (ZipCodeLookupRequest) This query parameter defines the XML payload. and it can not be passed in the body <ZipCodeLookupRequest USERID="XXXXXX"> <Address> <Address1>Suite 6100</Address1> <Address2>185 Berry St</Address2> <City>San Francisco</City> <State>CA</State> </Address> </ZipCodeLookupRequest>

Responses

Response Schema: text/xml

object

FirmName	string Example: "XYZ Corp" a company name
Address1	string Example: "210 King St" Delivery Address in the destination address. Required for all mail and packages, however 11-digit Destination Delivery Point ZIP+4 Code can be provided as an alternative in the Detail 1 Record.
Address2	string Example: "Suite 100" Delivery Address in the destination address. May contain secondary unit designator, such as APT or SUITE
City	string <= 15 characters Example: "San Francisco" City name of the destination address.
State	string <= 2 characters Example: "CA" Two-character state code of the destination address.
Zip5	string Example: "94556" Destination 5-digit ZIP Code. Numeric values (0-9) only. If International, all zeroes.
Zip4	string Destination ZIP+4 Numeric values (0-9) only. If International, all zeroes. Default to spaces if not available.
Urbanization	string <= 28 characters For Puerto Rico addresses only.
ReturnText	string Example: "Default address - The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address."
	object

Response samples

200

Content type

text/xml

<ZipCodeLookupResponse> <Address> <Address1>STE 6100</Address1> <Address2>185 BERRY ST</Address2> <City>SAN FRANCISCO</City> <State>CA</State> <Zip5>94107</Zip5> <Zip4>1741</Zip4> </Address> </ZipCodeLookupResponse>

Domestic Mail Service

Domestic Mail Service Standards

Priority Mail

The Priority Mail Service Standards API receives requests and returns the number of days (on average) it will take a Priority Mail package to arrive at its destination. Ensure that end-users understand that these are service standards and not guaranteed commitments. The Priority Mail Service Standards API processes a single request

Priority Mail Service

query Parameters

API required	string Default: "PriorityMail" API type
required	object (PriorityMailRequest) XML payload <PriorityMailRequest USERID=”XXXXXXXXXXXX”> <OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> </PriorityMailRequest>

Responses

Response Schema: text/xml

OriginZip required	string Example: "90210" Origination and destination Zip Codes must be valid. Either the first 3 digits or first 5 digits of the Zip Code are entered between the open tag and close tag.
DestinationZip required	string Example: "20770" Origination and destination Zip Codes must be valid and must be 5 digits.
Days	string Example: "3" Numbers of days expected to deliver.
IsGuaranteed	string Example: "Y" Is the delivery guaranteed.
Msg	string Example: "Your shipment may be delayed due to transportation issues" Service Standards Messaging. Appears when applicable.
EffectiveAcceptanceDate	string Example: "2022-02-23" Effective Acceptance Date is returned when is specified in the request.
ScheduledDeliveryDate	string Example: "2022-02-26" Scheduled Delivery Date is returned when is specified in the request.

Response samples

200

Content type

text/xml

<PriorityMailResponse> <OriginZip>90210</OriginZip> <DestinationZip>94556</DestinationZip> <Days>4</Days> <EffectiveAcceptanceDate>2022-02-24</EffectiveAcceptanceDate> <ScheduledDeliveryDate>2022-02-28</ScheduledDeliveryDate> </PriorityMailResponse>

StandardB

The Package Services “StandardB” API receives requests and returns the average number of days it will take a package to arrive at its destination. There are four types of Package Services: Standard Post, Bound Printed Matter, Library Mail, and Media Mail. The Package Services “StandardB” API processes a single request. Ensure that end-users understand that these are service standards and not guaranteed commitments.

Standard B Service

query Parameters

API required	string Default: "StandardB" API type
required	object (StandardBRequest) XML payload <StandardBRequest USERID=”XXXXXXXXXXXX”> <OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> </StandardBRequest>

Responses

Response Schema: text/xml

OriginZip required	string Example: "90210" Origination and destination Zip Codes must be valid. Either the first 3 digits or first 5 digits of the Zip Code are entered between the open tag and close tag.
DestinationZip required	string Example: "20770" Origination and destination Zip Codes must be valid and must be 5 digits.
Days	string Example: "3" Numbers of days expected to deliver.
Msg	string Example: "Your shipment may be delayed due to transportation issues" Service Standards Messaging. Appears when applicable.
EffectiveAcceptanceDate	string Example: "2022-02-23" Effective Acceptance Date is returned when is specified in the request.
ScheduledDeliveryDate	string Example: "2022-02-26" Scheduled Delivery Date is returned when is specified in the request.

Response samples

200

Content type

text/xml

<StandardBResponse> <OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> <Days>7</Days> </StandardBResponse>

First Class Mail

The First Class Mail Service Standards API receives requests and returns the average number of days it will take a package to arrive at its destination. The First Class Mail Service Standards API processes a single request. Ensure that end-users understand that these are service standards and not guaranteed commitments.

First Class Mail Service

query Parameters

API required	string Default: "FirstClassMail" API type
required	object (FirstClassMailRequest) XML payload <FirstClassMailRequest USERID=”XXXXXXXXXXXX”> <OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> </FirstClassMailRequest>

Responses

Response Schema: text/xml

OriginZip required	string Example: "90210" Origination and destination Zip Codes must be valid. Either the first 3 digits or first 5 digits of the Zip Code are entered between the open tag and close tag.
DestinationZip required	string Example: "20770" Origination and destination Zip Codes must be valid and must be 5 digits.
Days	string Example: "3" Numbers of days expected to deliver.
Msg	string Example: "Your shipment may be delayed due to transportation issues" Service Standards Messaging. Appears when applicable.
EffectiveAcceptanceDate	string Example: "2022-02-23" Effective Acceptance Date is returned when is specified in the request.
ScheduledDeliveryDate	string Example: "2022-02-26" Scheduled Delivery Date is returned when is specified in the request.

Response samples

200

Content type

text/xml

<FirstClassMailResponse> <OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> <Days>3</Days> </FirstClassMailResponse>

Express Mail Commitment

The Express Mail Service Commitments API provides delivery commitments for Express Mail packages for the given Zip Codes to include package drop-off information. A user provides an origination and a destination Zip Code and an optional current or future date that the package will be shipped.

Express Mail Commitment Service

query Parameters

API required	string Default: "ExpressMailCommitment" API type
required	object (ExpressMailCommitmentRequest) XML payload <ExpressMailCommitmentRequest USERID="XXXXXXXXXXXXX"> <OriginZIP>63123</OriginZIP> <DestinationZIP>89301</DestinationZIP> <Date>05-26-2021</Date> <DropOffTime>09:00</DropOffTime> <ReturnDates>true</ReturnDates> <PMGuarantee>Y</PMGuarantee> </ExpressMailCommitmentRequest>

Responses

Response Schema: text/xml

OriginZip

required

string

Example: "90210"

Origination and destination Zip Codes must be valid. Either the first 3 digits or first 5 digits of the Zip Code are entered between the open tag and close tag.

OriginCity

required

string

Example: "San Francisco"

Originating City

OriginState

required

string

Example: "CA"

Originating State

DestinationZip

required

string

Example: "92025"

Origination and destination Zip Codes must be valid and must be 5 digits.

DestinationCity

required

string

Example: "San Diego"

Destination city of the mail

DestinationState

required

string

Example: "CA"

Destination state of the mail

Date

required

string <date>

Example: "05-May-2021"

Date package is shipped. Can be left blank. Can use formats MM/DD/YYYY or DD-MMM-YYYY.

Time

required

string

Example: "13:00"

Date package is shipped. Can be left blank. Can use formats MM/DD/YYYY or DD-MMM-YYYY.

ExpeditedTransMessage

string

Example: "3"

Expedited Transportation Message. Returned when applicable and the request has the ReturnDates set to true.

MsgCode

string

Value: "TM103"

Example: "TM103"

Message Code. Returned when applicable and the request has the ReturnDates set to true.

Msg

string

Example: "Your shipment may be delayed due to transportation issues"

Message Text. Returned when applicable and the request has the ReturnDates set to true.

EffectiveAcceptanceDate

string

Example: "2022-02-23"

Effective Acceptance Date is returned when is specified in the request.

Array of objects [ 0 .. 5 ] items [ items ]

Array ([ 0 .. 5 ] items)

CommitmentName	string Enum: "1-Day" "2-Day" "3-Day" "DPO" "Military" Example: "2-Day" Commitment Name
CommitmentTime	string Example: "6:00 PM" Commitment Time. (eg: 6:00 PM)
CommitmentSequence	string Enum: "A0118" "B0118" "A0218" "B0218" Example: "A0218" Seq # equates to a specific Service Standard. A0118 = 1-Day at 6:00 PM, B0118 = 1-Day at 6:00 PM, A0218 = 2-Day at 6:00 PM, B0218=2-Day at 6:00 PM
	object Groups drop off location information.

Response samples

200

Content type

text/xml

<ExpressMailCommitmentResponse> <OriginZIP>63123</OriginZIP> <OriginCity>SAINT LOUIS</OriginCity> <OriginState>MO</OriginState> <DestinationZIP>89301</DestinationZIP> <DestinationCity>ELY</DestinationCity> <DestinationState>NV</DestinationState> <Date>26-May-2021</Date> <Time>9:00AM</Time> <EffectiveAcceptanceDate>2021-05-26</EffectiveAcceptanceDate> <Commitment> <CommitmentName>2-Day</CommitmentName> <CommitmentTime>6:00 PM</CommitmentTime> <CommitmentSequence>A0218</CommitmentSequence> <Location> <ScheduledDeliveryDate>2021-05-28</ScheduledDeliveryDate> <CutOff>5:30 PM</CutOff> <Facility>POST OFFICE</Facility> <Street>55 GRASSO PLZ</Street> <City>SAINT LOUIS</City> <State>MO</State> <Zip>63123</Zip> </Location> </Commitment> <Commitment> <CommitmentName>2-Day</CommitmentName> <CommitmentTime>6:00 PM</CommitmentTime> <CommitmentSequence>B0218</CommitmentSequence> <Location> <ScheduledDeliveryDate>2021-05-28</ScheduledDeliveryDate> <CutOff>5:30 PM</CutOff> <Facility>POST OFFICE</Facility> <Street>55 GRASSO PLZ</Street> <City>SAINT LOUIS</City> <State>MO</State> <Zip>63123</Zip> </Location> </Commitment> </ExpressMailCommitmentResponse>

Package Track & Confirm

To obtain Package Tracking API (API=TrackV2) access, users will need to contact the USPS Web Tools Program Office to request access and supply additional information for customer verification.

Note: This applies to both TrackV2 API simplified track requests (i.e., “TrackRequest”) and TrackV2 API detailed track requests (i.e., “TrackFieldRequest”). Users should follow these steps to submit a request for Tracking APIs access:

Navigate to: https://usps.force.com/emailus/s/web-tools-inquiry and provide user name (Web Tools User ID), select “Tracking APIs”, select “Track API” and submit the request with the following information below in the “Additional Information” text box:

Web Tools UserID
Mailer ID (MID)
Company Name
Requester First and Last Name
Requester Email
Requester Phone number
Mailing Address
Mailing City
Mailing State
Mailing Zip Code
PROD Registration Date
API access requested: Package Tracking (API=TrackV2)
Anticipated volume
Any additional information from the customer

Four service APIs are offered in conjunction with “Revision=1” of the Package Tracking “Fields” API: Track and Confirm by Email, Proof of Delivery, Tracking Proof of Delivery, and Return Receipt Electronic. The response data from Track/Confirm Fields request determines which services are available for a tracking ID. Each request input to the Web Tools server for the tracking service APIs is limited to one tracking ID. These APIs require additional permissions from the Web Tools Program Office in order to gain

USPS Web Tools User Guide access. When you request access for these APIs, please identify your anticipated API volume, mailer ID, and how you will be utilizing this API. A mailer identification number (MID) is a 6 or 9-digit number assigned to a customer through the USPS Business Customer Gateway (BCG). Please refer to the following links for help:

https://gateway.usps.com/eAdmin/view/knowledge?securityId=MID • https://postalpro.usps.com/mailing/mailer-id

Package Tracking

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.

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.

Package Tracking

query Parameters

API required	string Default: "TrackV2" API type
required	object (TrackRequest) XML payload <TrackRequest USERID="XXXXXXXXXXXX"> <TrackID ID="XXXXXXXXXXX1"></TrackID> <TrackID ID="XXXXXXXXXXX2"></TrackID> </TrackRequest>

Responses

Response Schema: text/xml

object

Integer value used to return of all available response fields. Set this value to 1 to return all currently documented response fields.

ID	string Default: "826ADISY3274" This attribute specifies your Web Tools ID. (aka your API KEY) See the Developers Guide for information on obtaining your USERID.
TrackSummary	string Example: "Your item was delivered at 6:50am on February 6 in BARTOW FL 33830."
TrackDetail	string Example: "February 6 6:49 am NOTICE LEFT BARTOW FL 33830"

Response samples

200

Content type

text/xml

<TrackResponse> <TrackInfo ID="XXXXXXXXXXX1"> <TrackSummary> Your item was delivered at 6:50 am on February 6 in BARTOW FL33830.</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> </TrackResponse>

Package Tracking Fields

query Parameters

API required	string Default: "TrackV2" API type
required	object (TrackFieldRequest) XML payload <TrackFieldRequest USERID="XXXXXXXXXXXX"> <Revision>1</Revision> <ClientIp>122.3.3</ClientIp> <SourceId>XYZ Corp</SourceId> <TrackID ID="XXXXXXXXXXXXXXXX"/> </TrackFieldRequest>

Responses

Response Schema: text/xml

required

object

Integer value used to return of all available response fields. Set this value to 1 to return all currently documented response fields.

ID required	string Default: "826ADISY3274" This attribute specifies your Web Tools ID. (aka your API KEY) See the Developers Guide for information on obtaining your USERID.
required	object Tracking Summary Information
required	object Tracking Detail Information. This group is repeatable
GuaranteedDeliveryDate	string <date> Example: "March 5, 2022" Global Express Mail only: certain countries provide a guarantee delivery.
RequestSeqNumber	number Example: "122" A unique identification number for a request. The same number that was provided in the request.
AdditionalInfo	string Additional package information
ADPScripting	string Additional ADP scripting specific to the ADP Type code
ArchiveRestoreInfo	string Example: "Yes" Information regarding availability of Restore service function
AssociatedLabel	string Example: "EA123456785US" Additional Label on the mail piece
CarrierRelease	boolean Example: "False" Field indicating the item qualifies for the customer to electronically authorize shipment release.
Class	string Example: "True" Mail Class of the mail piece (human readable). This will also include the service standard message if it exists.
ClassofMailCode	string Example: "CP" Mail Class of the mail piece (code).
DestinationCity	string Example: "NEW ORLEANS" The destination city.
DestinationCountryCode	string Example: "US" The destination country code
DestinationState	string Example: "LA" The destination State
DestinationZip	string Example: "70117" The destination ZIP code
EditedLabelID	string Example: "EA123456795US" Edited Label ID or Full Label ID. Used only when Source ID is IVR
EmailEnabled	boolean Example: "false" Signifies if USPS Tracking by Email service is enabled.
EndOfDay	string Example: "5:00pm" Populated with the end of day time provided by TRP when TRP API indicates the window is “End of Day” or when the piece is eligible for the PTR default end of day.
eSOFEligible	boolean Example: "false" Signifies if the mailpiece is eSOF eligibile.
ExpectedDeliveryDate	string Example: "December 31, 2022" Expected delivery date.
ExpectedDeliveryTime	string Example: "3:00 PM" Expected Delivery Time
ExpectedDeliveryType	string Example: "Expected Delivery by" Populates "Expected Delivery by" if there is an EDD.
GuaranteedDeliveryTime	string Example: "3:00 PM" Guaranteed Delivery Time provided for Priority Mail Express.
GuaranteedDeliveryType	string Example: "Scheduled Delivery by" Populates "Scheduled Delivery by" if there is a GDD
GuaranteedDetails	string Example: "Loss Only Guarantee" Special messaging related to the guarantee.
ItemShape	string Enum: "Letter" "Flat" "Parcel" "Unknown" Indicates the shape of the item.
KahalaIndicator	boolean Example: "False" no description
MailTypeCode	string Example: "DM" no description
MPDATE	string Example: "2019-08-21 10:44:08.000000" Internal date stamp
MPSUFFIX	string Example: "999999999" Internal suffix
OnTime	boolean Example: "False" Field indicating if the item will be delivered on time as specified in the Expected or Guaranteed delivery date.
OriginCity	string Example: "San Francisco" The origin city
OriginCountryCode	string Example: "US" The origin country code
OriginState	string Example: "CA" The origin state
OriginZip	string Example: "94107" The origin ZIP code
PodEnabled	boolean Example: "True" Signifies if Proof of Delivery service is enabled
PredictedDeliveryDate	string Example: "December 30, 2022" Predicted delivery date
PredictedDeliveryTime	string Example: "3:00 PM" Predicted Delivery Time
PredictedDeliveryType	string Example: "Expected Delivery on" Populates "Expected Delivery "by or on", if the source of the PDD is TRP API. Populates "Expected Delivery on" if the source of the PDD is a PTR calculated date.
PredictedDeliverySource	string Example: "TRP" States which system provided the Predicted Delivery prediction. TRP, AA
PDWStart	string Example: "11:00am" Predicted Delivery Window start time in am/pm format. In an EndOfDay scenario, the PDWStart tag is null.
PDWEnd	string Example: "1:00pm" Predicted Delivery Window end time in am/pm format. In an EndOfDay scenario, the PDWEnd tag is null.
PurgeByDate	string <date> Example: "December 31, 2024" Contains the Purge By Date of the mail piece.
RelatedRRID	string Example: "EA123456795US" The related label ID between a tracking barcode, the core product, and a PS3811, Green Card Return Reciept. This field can contain either the core product label ID or the Green Card label ID. There is only a one to one relationship. Core Product ID: EA123456795US Or Green Card ID; 9590940112345671234567
RedeliveryEnabled	boolean Example: "False" Field indicating if the item qualifies for redelivery.
RestoreEnabled	boolean Example: "False" Signifies if Restore tracking information service is enabled
ReturnDateNotice	string Example: "December 1, 2022" Field indicating the date the item will be Returned to Sender.
TpodEnabled	boolean Example: "False" Signifies if Tracking Proof of Delivery service is enabled
RRAMenabled	boolean Example: "False" Signifies if RRAM service is enabled
RreEnabled	boolean Example: "False" Signifies if Return Receipt Electronic service is enabled
Service	string Example: "PO to Addressee" Additional services purchased
ServiceTypeCode	string Example: "701" Service Type Code of the mail piece M, AD, VI, 03, 70, 716
Status	string Example: "Delivered" Package status
StatusCategory	string Example: "In Transit" Package status category
StatusSummary	string Example: "Your item was delivered at 12:55 pm on April 05, 2010 in FALMOUTH, MA 02540" Status summary
TABLECODE	string Example: "T" Internal description of mail piece as it relates to PTR (live, history, or archived piece) T, H, A (CMC830 V3 – T is the only value defined)
ValueofArticle	string Value of Article for when the Source ID is PIN
	object error object returned by the API

Response samples

200

Content type

text/xml

<TrackResponse> <TrackInfo ID="XXXXXXXXXXXXXXXXXX">  <TrackSummary> <EventTime>10:45 pm</EventTime>  <EventDate>January 6, 2016</EventDate>  <Event>Arrived at USPS Facility</Event>  <EventCity>COLUMBUS</EventCity>  <EventState>OH</EventState>  <EventZIPCode>43218</EventZIPCode>  <EventCountry></EventCountry>  <FirmName></FirmName>  <Name></Name>  <AuthorizedAgent>false</AuthorizedAgent>  </TrackSummary> <TrackDetail> <EventTime>9:10 am</EventTime> <EventDate>January 6, 2016</EventDate> <Event>Acceptance</Event> <EventCity>LAKE CHARLES</EventCity> <EventState>IL</EventState> <EventZIPCode>12345</EventZIPCode> <EventCountry></EventCountry> <FirmName></FirmName> <Name></Name> <AuthorizedAgent>false</AuthorizedAgent> </TrackDetail> </TrackInfo> </TrackResponse>

Track & Confirm by Email

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:

Track & Confirm by Email

query Parameters

API

required

string

Default: "PTSEmail"

API type

required

object (PTSEmailRequest)

XML payload

<PTSEmailRequest USERID="XXXXXXXXXXXX">
<TrackId>XXXXXXXXXXX</TrackId >
<ClientIp>127.2.0.1</ClientIp>
<SourceId>XYZ Corp</SourceId>
<MpSuffix >9402</MpSuffix>
<MpDate >2021-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>

Responses

Response Schema: text/xml

ResultText	string Example: "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." Status message
ReturnCode	string Example: "0" Return code

Response samples

200

Content type

text/xml

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

Proof of Delivery

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:

Proof of Delivery

query Parameters

API

required

string

Default: "PTSPod"

API type

required

object (PTSPodRequest)

XML payload

<PTSPodRequest USERID="XXXXXXXXXXXX">
<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>

Responses

Response Schema: text/xml

ResultText	string Example: "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." Status message
ReturnCode	string Example: "0" Return code

Response samples

200

Content type

text/xml

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

Return Receipt Electronic

The Return Receipt Electronic API allows the customer to request a copy of the proof of delivery record via email. When you request access for this API, please identify your anticipated API volume, mailer ID and how you will be utilizing this API. A mailer identification number (MID) is a 6 or 9-digit number assigned to a customer through the USPS Business Customer Gateway (BCG). Please refer to the following links for help:

Return Receipt Electronic

query Parameters

API

required

string

Default: "PTSRre"

API type

required

object (PTSRreRequest)

XML payload

<PTSRreRequest USERID="XXXXXXXXXXXX">
<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>

Responses

Response Schema: text/xml

ResultText	string Example: "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." Status message
ReturnCode	string Example: "0" Return code

Response samples

200

Content type

text/xml

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

Track Proof of Delivery

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:

Track Proof of Delivery

query Parameters

API

required

string

Default: "PTSTPod"

API type

required

object (PTSTPodRequest)

XML payload

<PTSTPodRequest USERID="XXXXXXXXXXXX">
<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>IVR</SourceId>
</PTSTPodRequest>

Responses

Response Schema: text/xml

ResultText	string Example: "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." Status message
ReturnCode	string Example: "0" Return code

Response samples

200

Content type

text/xml

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

Rate Calculation

USPS Web Tools - Domestic Rate Calculator

Domestic

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.

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.

Rate Calculator

query Parameters

API required	string Default: "RateV4" API type
required	object (RateV4Request) XML payload <RateV4Request USERID="XXXXXX"> <Revision>2</Revision> <Package ID="0"> <Service> PRIORITY </Service> <ZipOrigination>2201</ZipOrigination> <ZipDestination>26301</ZipDestination> <Pounds>8</Pounds> <Ounces>2</Ounces> <Container></Container> <Machinable>TRUE</Machinable> </Package> </RateV4Request>

Responses

Response Schema: text/xml

USERID

required

string

Default: "826ADISY3274"

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

required

Array of objects[ items ]

Array

required	Array of objects[ items ] Postage tag contains a nested postal rate and service description.
ZipOrigination required	string Example: "10101" ZIP code must be valid.
ZipDestination required	string Example: "54324" ZIP code must be valid.
Pounds required	integer [ 0 .. 70 ] Example: "10" Value must be numeric. Package weight cannot exceed 70 pounds.
Ounces required	number <double> [ 1 .. 1120 ] Example: "8" Value must be numeric. Package weight cannot exceed 70 pounds (1120 ounces).
FirstClassMailType	string Enum: "LETTER" "FLAT" Example: "LETTER" Required when Service property is FIRST CLASS or FIRST CLASS COMMERCIAL or FIRST CLASS HFP COMMERCIAL. Note: The tag is returned only if the submitted is “First Class”. If any other is returned (Including “First Class Commercial”) the tag is used. Note: Flats are also known as Large Envelopes
Container	string Enum: "VARIABLE" "FLAT RATE ENVELOPE" "PADDED FLAT RATE ENVELOPE" "LEGAL FLAT RATE ENVELOPE" "SM FLAT RATE ENVELOPE" "WINDOW FLAT RATE ENVELOPE" "GIFT CARD FLAT RATE ENVELOPE" "SM FLAT RATE BOX" "MD FLAT RATE BOX" "LG FLAT RATE BOX" "REGIONALRATEBOXA" "REGIONALRATEBOXB" "CUBIC PARCELS" "CUBIC SOFT PACK" Example: "VARIABLE" Shipping Container (appears where applicable: Service=ALL or Service=PRIORITY EXPRESS or Service=PRIORITY
Machinable	boolean Example: "true" Machinable is required when: Service is FIRST CLASS and FirstClassMailType is LETTER OR FirstClassMailType is FLAT and Service is Retail Ground and ALL and ONLINE
Zone	string Example: "4" USPS defined distance codes assigned to each origin and destination ZIP Code pairing for every ZIP Code number in the nation. These distance codes, referred to as zones, are designated as "1 through 9"
	object Defines extra services in order to determine price and availability of additional services. An initial call without the SpecialService tag specified is recommended to determine base availability of special services for each mail class. Available when Revision="2" is included in the XML request
	object Error document (indicates request could not be completed). See the Error Responses section below.

Revision

string

Example: "2"

Set this value to “2” to return all currently documented response fields.

Response samples

200

Content type

text/xml

<RateV4Response> <Package ID="0"> <ZipOrigination>22201</ZipOrigination> <ZipDestination>26301</ZipDestination> <Pounds>8</Pounds> <Ounces>2</Ounces> <Container>VARIABLE</Container> <Zone>3</Zone> <Postage CLASSID="1"> <MailService>Priority Mail 3-Day&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt;</MailService> <Rate>14.10</Rate> <SpecialServices> <SpecialService> <ServiceID>119</ServiceID> <ServiceName>Adult Signature Required</ServiceName> <Available>true</Available> <Price>8.50</Price> </SpecialService> <SpecialService> <ServiceID>120</ServiceID> <ServiceName>Adult Signature Restricted Delivery</ServiceName> <Available>true</Available> <Price>8.75</Price> </SpecialService> <SpecialService> <ServiceID>104</ServiceID> <ServiceName>Certificate of Mailing (Form 3817)</ServiceName> <Available>true</Available> <Price>1.65</Price> </SpecialService> <SpecialService> <ServiceID>105</ServiceID> <ServiceName>Certified Mail&amp;lt;sup&amp;gt;&amp;#174;&amp;lt;/sup&amp;gt;</ServiceName> <Available>true</Available> <Price>3.75</Price> </SpecialService> <SpecialService> <ServiceID>170</ServiceID> <ServiceName>Certified Mail&amp;lt;sup&amp;gt;&amp;#174;&amp;lt;/sup&amp;gt; Restricted Delivery</ServiceName> <Available>true</Available> <Price>9.75</Price> </SpecialService> <SpecialService> <ServiceID>171</ServiceID> <ServiceName>Certified Mail&amp;lt;sup&amp;gt;&amp;#174;&amp;lt;/sup&amp;gt; Adult Signature Required</ServiceName> <Available>true</Available> <Price>9.75</Price> </SpecialService> <SpecialService> <ServiceID>172</ServiceID> <ServiceName>Certified Mail&amp;lt;sup&amp;gt;&amp;#174;&amp;lt;/sup&amp;gt; Adult Signature Restricted Delivery</ServiceName> <Available>true</Available> <Price>9.75</Price> </SpecialService> <SpecialService> <ServiceID>103</ServiceID> <ServiceName>Collect on Delivery</ServiceName> <Available>true</Available> <Price>8.60</Price> <DeclaredValueRequired>true</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService> <ServiceID>175</ServiceID> <ServiceName>Collect on Delivery Restricted Delivery</ServiceName> <Available>true</Available> <Price>14.45</Price> <DeclaredValueRequired>true</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService> <ServiceID>125</ServiceID> <ServiceName>Insurance</ServiceName> <Available>true</Available> <Price>0.00</Price> <DeclaredValueRequired>true</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService> <ServiceID>179</ServiceID> <ServiceName>Insurance Restricted Delivery</ServiceName> <Available>true</Available> <Price>0.00</Price> <DeclaredValueRequired>true</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService> <ServiceID>109</ServiceID> <ServiceName>Registered Mail&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt;</ServiceName> <Available>true</Available> <Price>13.75</Price> <DeclaredValueRequired>true</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService> <ServiceID>176</ServiceID> <ServiceName>Registered Mail&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt; Restricted Delivery</ServiceName> <Available>true</Available> <Price>19.60</Price> <DeclaredValueRequired>true</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService> <ServiceID>181</ServiceID> <ServiceName>Scan Retention</ServiceName> <Available>true</Available> <Price>0.99</Price> <DeclaredValueRequired>false</DeclaredValueRequired> <DueSenderRequired>false</DueSenderRequired> </SpecialService> <SpecialService> <ServiceID>108</ServiceID> <ServiceName>Signature Confirmation&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt;</ServiceName> <Available>true</Available> <Price>3.45</Price> </SpecialService> <SpecialService> <ServiceID>173</ServiceID> <ServiceName>Signature Confirmation&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt; Restricted Delivery</ServiceName> <Available>true</Available> <Price>9.30</Price> </SpecialService> <SpecialService> <ServiceID>156</ServiceID> <ServiceName>Signature Confirmation&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt; Electronic</ServiceName> <Available>true</Available> <Price>2.90</Price> </SpecialService> <SpecialService> <ServiceID>174</ServiceID> <ServiceName>Signature Confirmation&amp;lt;sup&amp;gt;&amp;#8482;&amp;lt;/sup&amp;gt; Electronic Restricted Delivery</ServiceName> <Available>true</Available> <Price>8.75</Price> </SpecialService> <SpecialService> <ServiceID>190</ServiceID> <ServiceName>Special Handling - Fragile</ServiceName> <Available>true</Available> <Price>12.15</Price> </SpecialService> <SpecialService> <ServiceID>106</ServiceID> <ServiceName>USPS Tracking&amp;lt;sup&amp;gt;&amp;#174;&amp;lt;/sup&amp;gt;</ServiceName> <Available>true</Available> <Price>0.00</Price> </SpecialService> <SpecialService> <ServiceID>155</ServiceID> <ServiceName>USPS Tracking&amp;lt;sup&amp;gt;&amp;#174;&amp;lt;/sup&amp;gt; Electronic</ServiceName> <Available>true</Available> <Price>0.00</Price> </SpecialService> </SpecialServices> </Postage> </Package> </RateV4Response>