Description

This API supports the service standards for the number of days between the acceptance and delivery of a piece of mail that the Postal Service™ considers to be timely delivery. Service standards are delivery benchmarks for how long customers can expect for the Postal Service to deliver different types of mail from origin to destination — Point A to Point B. Service standards are not necessarily the same as the actual service performance.

Service Standards (3.1.5)

Download OpenAPI specification:Download

This document contains a Reference Guide to the Service Standards API's listed below:

This API provides estimated delivery standard information for ZIP Code™s with 3 or 5 digits, while taking into account non-delivery days. It covers multiple mail classes, such as Priority Mail Express®, Priority Mail Express® (for live animals), Priority Mail®, First-Class Mail® Letters, First-Class Mail® Flats, First-Class Mail® Cards, USPS Ground Advantage™, Bound Printed Matter, First Class Mail®, Library Mail, Media Mail®, Parcel Select®, and Parcel Select Lightweight®. To utilize this API, users need to refer to Pub 199 for Service Type Codes.

Authentication, Authorization and Access Control

Client applications are given authorized access to protected information resources. Authorization is accomplished via the USPS® Customer Onboarding Platform, where Customer Registration users may grant applications access to their protected business information. All client applications must go through this onboarding process. Any Customer Registration user wishing to share their protected business information with client application(s) may also grant authorized access.

The OAuth2, version 3 (/v3) API is based on this authorization grant and must be used to get tokens for all V3 APIs. The resulting OAuth2 access token is to be placed in the Authorization header, using the Bearer authentication scheme. This is like what is done for all version 1 (/v1) APIs. All version 3 APIs validate access to protected information resources and will respond with a 401 HTTP status, Unauthorized reason, when the client application has not been authorized to access the given information resource.

Publication 199

Resources

Allows customers to get estimates on delivery standards.

Allows customers to get estimates on delivery standards between 3 or 5 digit ZIP Code™s for the selected mail classes. When requesting estimates for USPS_GROUND_ADVANTAGE two estimates will be returned (one for packages greater than or equal to a pound and one for packages less than a pound, this will be called out in the notes field), unless a weight is provided.

Authorizations:
OAuth
query Parameters
originZIPCode
required
string [ 3 .. 9 ] characters \d{3}|\d{5}|\d{9}

The ZIP Code™ where the package is shipped from using either all 9 digits, 5 digits or first 3 digits.

destinationZIPCode
required
string [ 5 .. 9 ] characters \d{5}|\d{9}

The ZIP Code™ where the package is shipped to using either all 9 digits or 5 digits.

acceptanceDate
string <date>
Example: acceptanceDate=2023-06-20

Date Package will be mailed. Acceptance date may be up to 30 days in advance. Today's date is used if omitted.

acceptanceTime
string^([0-1][0-9]|2[0-3])[0-5][0-9]$
Example: acceptanceTime=0800

Time Package will be mailed. Today's time defaults to 8:00 am if omitted.

mailClass
string
Enum: "BOUND_PRINTED_MATTER" "FIRST-CLASS_PACKAGE_SERVICE" "CARDS" "FLATS" "LETTERS" "LIBRARY_MAIL" "MEDIA_MAIL" "PARCEL_SELECT" "PARCEL_SELECT_LIGHTWEIGHT" "PRIORITY_MAIL" "PRIORITY_MAIL_EXPRESS" "USPS_GROUND_ADVANTAGE" "ALL"

The Postal Service divides mail into different services, called "classes." Each class of mail has different features, service levels, postage prices, and presort requirements. Note: Mail class enumerations "LETTERS", "CARDS", and FLATS" are specific to First Class Mail only.

destinationType
string
Default: "STREET"
Enum: "STREET" "PO_BOX" "HOLD_FOR_PICKUP"

Destination type indicator for non-Expedited mailing. Defaults to 'STREET' if omitted.

serviceTypeCodes
string

Service Type Codes are designators used to represent USPS classes of mail in conjunction with the type of Extra Service(s) being requested. For a list of Service Type Codes to utilize in the API call please refer to Publication 199.

destinationEntryFacilityType
string
Enum: "NONE" "DESTINATION_NETWORK_DISTRIBUTION_CENTER" "DESTINATION_SECTIONAL_CENTER_FACILITY" "DESTINATION_DELIVERY_UNIT" "DESTINATION_SERVICE_HUB"

Types of Facilities

  • NONE
  • DESTINATION_NETWORK_DISTRIBUTION_CENTER
  • DESTINATION_SECTIONAL_CENTER_FACILITY
  • DESTINATION_DELIVERY_UNIT
  • DESTINATION_SERVICE_HUB
weight
number <double>

The weight of the package being shipped. Required if looking up USPS Ground Advantage estimates or standards. For getting estimates for ground advantage if package weight is greater than one pound, then weight is required.

weightUOM
string
Default: "lb"
Value: "lb"

Weight Unit of Measure

  • lb - Pounds

Responses

Response samples

Content type
[
  • {
    }
]

Allows customers to get standards.

Returns the average number of days it will take a package to arrive at its destination for the selected mail class. When requesting standards for USPS_GROUND_ADVANTAGE two standards will be returned (one for packages greater than or equal to a pound and one for packages less than a pound, this will be called out in the notes field), unless a weight is provided.

Authorizations:
OAuth
query Parameters
originZIPCode
required
string [ 3 .. 9 ] characters \d{3}|\d{5}|\d{9}

The ZIP Code™ where the package is shipped from using either all 9 digits, 5 digits or first 3 digits.

destinationZIPCode
required
string [ 5 .. 9 ] characters \d{5}|\d{9}

The ZIP Code™ where the package is shipped to using either all 9 digits or 5 digits.

mailClass
string
Enum: "BOUND_PRINTED_MATTER" "FIRST-CLASS_PACKAGE_SERVICE" "CARDS" "FLATS" "LETTERS" "LIBRARY_MAIL" "MEDIA_MAIL" "PARCEL_SELECT" "PARCEL_SELECT_LIGHTWEIGHT" "PRIORITY_MAIL" "PRIORITY_MAIL_EXPRESS" "USPS_GROUND_ADVANTAGE" "ALL"

The Postal Service divides mail into different services, called "classes." Each class of mail has different features, service levels, postage prices, and presort requirements. Note: Mail class enumerations "LETTERS", "CARDS", and FLATS" are specific to First Class Mail only.

destinationType
string
Default: "STREET"
Enum: "STREET" "PO_BOX" "HOLD_FOR_PICKUP"

Destination type indicator for non-Expedited mailing. Defaults to 'STREET' if omitted.

serviceTypeCodes
string

Service Type Codes are designators used to represent USPS classes of mail in conjunction with the type of Extra Service(s) being requested. For a list of Service Type Codes to utilize in the API call please refer to Publication 199.

destinationEntryFacilityType
string
Enum: "NONE" "DESTINATION_NETWORK_DISTRIBUTION_CENTER" "DESTINATION_SECTIONAL_CENTER_FACILITY" "DESTINATION_DELIVERY_UNIT" "DESTINATION_SERVICE_HUB"

Types of Facilities

  • NONE
  • DESTINATION_NETWORK_DISTRIBUTION_CENTER
  • DESTINATION_SECTIONAL_CENTER_FACILITY
  • DESTINATION_DELIVERY_UNIT
  • DESTINATION_SERVICE_HUB
weight
number <double>

The weight of the package being shipped. Required if looking up USPS Ground Advantage estimates or standards. For getting estimates for ground advantage if package weight is greater than one pound, then weight is required.

Responses

Response samples

Content type
[
  • {
    }
]