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
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.
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.
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.
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
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.
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.
API required | string Default: "Verify" This query parameter defines the resource you are accessing. For address verification your API query param value must equal |
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> |
object | |||||||||||||||||||||||||||||||||||||||||||
|
<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 Lookup API returns the city and state corresponding to the given ZIP Code. The CityStateLookup API processes up to five lookups per request.
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 |
required | object (CityStateLookupRequest) This query parameter defines the XML payload and it can not be passed in the body <CityStateLookupRequest USERID="XXXXXX"> |
object | |||||||||||
|
<CityStateLookupResponse> <ZipCode> <Zip5>94556</Zip5> <City>MORAGA</City> <State>CA</State> </ZipCode> </CityStateLookupResponse>
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.
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 |
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> |
object | |||||||||||||||||||||
|
<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>
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
API required | string Default: "PriorityMail" API type |
required | object (PriorityMailRequest) XML payload <PriorityMailRequest USERID=”XXXXXXXXXXXX”>
<OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> </PriorityMailRequest> |
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 |
ScheduledDeliveryDate | string Example: "2022-02-26" Scheduled Delivery Date is returned when |
<PriorityMailResponse> <OriginZip>90210</OriginZip> <DestinationZip>94556</DestinationZip> <Days>4</Days> <EffectiveAcceptanceDate>2022-02-24</EffectiveAcceptanceDate> <ScheduledDeliveryDate>2022-02-28</ScheduledDeliveryDate> </PriorityMailResponse>
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.
API required | string Default: "StandardB" API type |
required | object (StandardBRequest) XML payload <StandardBRequest USERID=”XXXXXXXXXXXX”>
<OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> </StandardBRequest> |
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 |
ScheduledDeliveryDate | string Example: "2022-02-26" Scheduled Delivery Date is returned when |
<StandardBResponse> <OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> <Days>7</Days> </StandardBResponse>
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.
API required | string Default: "FirstClassMail" API type |
required | object (FirstClassMailRequest) XML payload <FirstClassMailRequest USERID=”XXXXXXXXXXXX”>
<OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> </FirstClassMailRequest> |
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 |
ScheduledDeliveryDate | string Example: "2022-02-26" Scheduled Delivery Date is returned when |
<FirstClassMailResponse> <OriginZip>90201</OriginZip> <DestinationZip>21114</DestinationZip> <Days>3</Days> </FirstClassMailResponse>
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.
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> |
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 | ||||||||
Array of objects [ 0 .. 5 ] items [ items ] | |||||||||
Array ([ 0 .. 5 ] items)
|
<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>
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:
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:
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 returne