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

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

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

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

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

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

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

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:

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 returne