Open and Distribute API

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 3.1 (05/31/2015)

 

 

 

 

 

 

 


 


Contents

Introduction to Web Tools. 3

Before you get started: 3

Open and Distribute API. 3

Overview.. 3

Open / Distribute Priority Request 4

API Signature. 5

Request Descriptions. 5

Sample Request 12

Response Descriptions. 12

Sample Response. 14

Error Responses. 14

 


Introduction to Web Tools

This document contains a Reference Guide to the USPS Open and Distribute Label APIs. See the Developer’s Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and trouble-shooting.

 

Note: The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not be generated. The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response.

 

When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered.  Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values. For instance, a line of sample code may be:

 

<TrackID> EJ123456780US </TrackID>

 

In this instance, you will replace “EJ123456780US” with the tracking ID for the package.

Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Technical Documentation section of the Web Tools page on usps.com/webtools. 

For more information on Priority Mail Open and Distribute, see https://www.usps.com/ship/priority-mail.htm.

Open and Distribute API

Overview

Priority Mail Open and Distribute shipments expedite movement of any class of mail (except Express Mail) between the domestic origin and destination postal facility. The service is designed exclusively for all classes of mail commingled into an approved USPS container.  Postage is paid based on the weight of the entire contents of the Priority Mail Open and Distribute contain, excluding the tare weight of the container, and is zoned rated from the acceptance Post Office to the destination facility of the shipment.  The shipments receive Priority Mail service from the origin facility to the destination facility. Once received at the destination facility, the container address label barcode is scanned and the enclosed mail is processed appropriately to the mail class.

Mailers prepare Priority Mail Open and Distribute shipments according to standards for the enclosed class of mail and present their shipments to the business mail entry unit in enough time for acceptance, processing, and dispatch to the appropriate unit before the critical entry time.  Mailers must use the electronic format.

Open / Distribute Priority Request

Open and Distribute Service on address labels for Priority Mail Open and Distribute containers, in accordance with requirements in Publication 199, Intelligent Mail Package Barcode Implementation Guide.

The Priority Mail Open and Distribute bar coded label will enable customers to easily and conveniently view the tracking of their shipments.  The bar code label will increase package visibility.  The bar coded label with the service type code “123” will assist in improving scan performance and provide mailers accurate and consistent information on each Open and Distribute container. USPS supplied container tags of green Tag 161 going to mail processing facilities, pink Tag 190 for destination delivery units or orange Label 23 used for both processing and DDU’s, are provided for correct processing and handling of Priority Mail Open and Distribute shipments.  The five Priority Mail Open and Distribute address label barcodes are:

 

Drop Shipment Destination Facility

<FacilityType/>

<ToFacilityName/>

<ToFacilityAddress2/>

<ToFacilityCity/>
<ToFacilityState/>

<ToFacilityZip5/>

Destination Delivery Unit

DDU

Required

Required

Required when ZIP not provided

Required when City/State not provided

Sectional Center Facility

SCF

Leave blank

Leave blank

Required when AllowNonCleansedFacilityAddr=true

Required

Bulk Mail Center

BMC

Leave blank

Leave blank

Required when AllowNonCleansedFacilityAddr=true

Required

Area Distribution Center

ADC

Leave blank

Leave blank

Required when AllowNonCleansedFacilityAddr=true

Required

Auxiliary Service  Facility

ASF

Leave blank

Leave blank

Required when AllowNonCleansedFacilityAddr=true

Required

 

The facility address information can be obtained from Facility Access and Shipment Tracking (FAST) at https://fast.usps.com/fast/main.action .  Note that login is not required.  Using the Reports features, FAST will produce a “Drop Entry Point View” of available destinations for the Open and Distribute container based on the type and destination of the enclosed mailpieces.

For example, if the enclosed mail is being sent to ZIP codes starting with 441 via Standard mail, FAST will produce a listing similar to the one below.  The Open and Distribute container would be addressed to the appropriate facility based on the shape of the contents and proximity to the destination.

 

API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=OpenDistributePriorityV2

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=OpenDistributePriorityV2Certify

&XML=(see below)

 

Note: The “OpenDistributePriorityV2Certify” API signature is for testing purposes and will not generate usable labels and barcodes.

Request Descriptions

Tag Name

Occurs

Description

Type

Validation

OpenDistributePriorityV2.0Request

required once

API=OpenDistributePriorityV2

API=OpenDistributePriorityV2Certify

 

The "Certify" form of the request is used for integrator testing. It produces a label that is not suitable for mailing and must not be entered into the US Postal System. Certify requests do not require additional permissions to invoke.  

(group)

substitutionGroup=

"OpenDistributePriorityV2.0CertifyRequest"

OpenDistributePriorityV2.0Request / Option

optional

For future use.

empty

 

OpenDistributePriorityV2.0Request / Revision

optional

This is for versioning of the API's and for triggering response tags for future versions.

string

minLength=0

pattern=\d{1}

 

OpenDistributePriorityV2.0Request / ImageParameters

optional

For future use.

(group)

minOccurs="0"

OpenDistributePriorityV2.0Request / ImageParameters / ImageParameter

required

For future use. Required on request, leave blank.

string

minOccurs="0"

OpenDistributePriorityV2.0Request / PermitNumber

optional

Input Permit number provided by your local post office.  

string

pattern=\d{1,15}  

OpenDistributePriorityV2.0Request / PermitIssuingPOZip5

optional

ZIP Code of post office that issued your permit. REQUIRED when PermitNumber is specified. Must be valid within Address Matching System. City and State for Permit imprint are obtained from this ZIP code.  

string


pattern=\d{5}  

OpenDistributePriorityV2.0Request / FromName

required once

Name of sender.  

string

minLength=1
maxLength=38
  

OpenDistributePriorityV2.0Request / FromFirm

required once

Company name.  

string

minLength=0
maxLength=32
  

OpenDistributePriorityV2.0Request / FromAddress1

required once

Secondary address unit designator and number (such as an apartment or suite number (APT 202, STE 100)).  

string

minLength=0
maxLength=48
  

OpenDistributePriorityV2.0Request / FromAddress2

required once

Street number and name. Includes predirectional, suffix, and postdirectional for the address or rural route and box number (RR 5 BOX 10), highway contract route and box number (HC 4 BOX 45), or post office box number (PO BOX 458).  

string

minLength=1
maxLength=48
  

OpenDistributePriorityV2.0Request / FromCity

required once

The city is any acceptable mailing name for the 5-digit ZIP code serving the intended recipient.  

string

minLength=1
maxLength=28
  

OpenDistributePriorityV2.0Request / FromState

required once

Use only official USPS state name abbreviations.  

string

pattern=\w{2}  

valid state

OpenDistributePriorityV2.0Request / FromZip5

required once

Correct 5-digit ZIP Code.  

string

pattern=\d{5}  

OpenDistributePriorityV2.0Request / FromZip4

required once

Last four digits of a complete ZIP+4 code.  

string

minLength=0
pattern=\d{4}

OpenDistributePriorityV2.0Request / POZipCode

optional

When the ZIP Code of a collection point for a given package is different from the Zip Code of the person mailing the package (their return address), this tag must be used to convey this difference to the USPS. Enter the ZIP Code of the post office or collection box where the item is mailed. May be different than "FromZip5."  

string

minLength=0
pattern=\d{5}

OpenDistributePriorityV2.0Request / ToFacilityName

required once

Drop Shipment destination facility name. Required for OpenDistributePriorityV2.0Request[FacilityType='DDU']. Truncated to 26 characters on label.  

string

minLength=0
maxLength=38
  

OpenDistributePriorityV2.0Request / ToFacilityAddress1

required once

Drop Shipment destination facility secondary address unit designator and number. Truncated to 32 characters after address standardization for label.  

string

minLength=0
maxLength=38
  

OpenDistributePriorityV2.0Request / ToFacilityAddress2

required once

Drop Shipment destination facility street number and name. OpenDistributePriorityV2.0Request[FacilityType='DDU']. Truncated to 32 characters after address standardization for label.  

string

minLength=0
maxLength=38
  

OpenDistributePriorityV2.0Request / ToFacilityCity

required once

Drop Shipment destination facility city. When OpenDistributePriorityV2.0Request[FacilityType ='DDU'], either City and State, or ZIP code is REQUIRED. Truncated to 15 characters after address standardization for label.  

string

minLength=0
maxLength=28
  

OpenDistributePriorityV2.0Request / ToFacilityState

required once

Drop Shipment destination facility state abbreviation. When OpenDistributePriorityV2.0Request[FacilityType='DDU'], either City and State, or ZIP code is REQUIRED.  

string

minLength=0
pattern=\w{2}

OpenDistributePriorityV2.0Request / ToFacilityZip5

required once

Drop Shipment destination facility 5-digit ZIP code. When OpenDistributePriorityV2.0Request[FacilityType='DDU'], either City and State, or ZIP code is REQUIRED. For all other FacilityType values, always REQUIRED and must be valid ZIP code.  

string

minLength=0
pattern=\d{5}

OpenDistributePriorityV2.0Request / ToFacilityZip4

required once

Drop Shipment destination facility last four digits of ZIP+4. May be REQUIRED to obtain exact address match when OpenDistributePriorityV2.0Request[FacilityType='DDU'].  

string

minLength=0
pattern=\d{4}

OpenDistributePriorityV2.0Request / ToFacilityPOBoxFlag

optional

Indicates that the ToFacility address is a PO Box.

boolean

default=false

OpenDistributePriorityV2.0Request  / ToContactPreference

required once

This indicates how the recipient will be notified that the package is available for pickup. Specify WAIVED if notification is not desired.


For example: <ToContactPreference>EMAIL</ToContactPreference> 

string

Enumerations:

EMAIL

SMS

WAIVED

 

default=EMAIL

OpenDistributePriorityV2.0Request / ToContactMessaging

required once

This contains the text messaging address or is blank depending on the ToContactPreference tag.

This value must be a syntactically-valid SMS number. If WAIVED is used, this value must be blank.


For example: <ToContactMessaging>5701234567</ToContactMessaging> 

string

maxLength=64


OpenDistributePriorityV2.0Request  / ToContactEMail

optional

This contains the email address or is blank depending on the ToContactPreference tag.

This value must be a syntactically-valid e-mail address. If WAIVED is used, this value must be blank.


For example: <ToContactMessaging>user@anydomain.gov</ToContactMessaging> 

string

maxLength=64
valid email address  

OpenDistributePriorityV2.0Request / FacilityType

required once

Drop Shipment destination facility type. Has values: "DDU", "SCF", "BMC", "ADC", "ASF".  

string


Enumerations:

DDU
SCF
BMC
ADC
ASF  

OpenDistributePriorityV2.0Request / MailClassEnclosed

required once

Mail Class and Processing Category, displays on label as: Letters: Standard Mail Letters; Flats: Standard Mail Flats; Parcels: Standard Mail Parcels; Mixed: Standard Mail Mixed; Other: explanation from OpenDistributePriorityV2.0Request/MailClassOther tag.  

string


Enumerations:

LETTERS

FLATS

PARCELS

MIXED

OTHER

OpenDistributePriorityV2.0Request / MailClassOther

optional

Explanation, REQUIRED when OpenDistributePriorityV2.0Request[MailClassEnclosed='Other']. Is displayed on the label as provided.  

string

minLength=0
maxLength=21
  

OpenDistributePriorityV2.0Request / WeightInPounds

optional

(Estimated) weight of package in pounds. Number must be represented using at most eight characters.  

decimal

minInclusive=0
maxInclusive=70
  

OpenDistributePriorityV2.0Request / WeightInOunces

optional

(Estimated) weight of package in ounces. Number must be represented using at most eight characters.  

integer

maxInclusive=1120
minInclusive=0
  

OpenDistributePriorityV2.0Request / ImageType

required once

The type of label image desired.  

string

Enumerations:

TIF

PDF

NONE

OpenDistributePriorityV2.0Request / SeparateReceiptPage

optional

Enter "true" for the shipping label and the online customer record to be printed on two separate pages or "false" for both printed on the same page.  

boolean

default=false
  

OpenDistributePriorityV2.0Request / LabelDate

optional

Date package will be mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in either format:

 

yyyy-mm-dd

dd-mmm-yyyy, such as 10-Jan-2010, or

mm/dd/yyyy, such as 01/10/2010.

 

For example:

<LabelDate>2015-05-05 </LabelDate>

string

minLength=0

pattern=yyyy-mm-dd

pattern=mm\dd\yyyy

pattern= dd-mmm-yyyy

OpenDistributePriorityV2.0Request / CustomerRefNo

optional

For future use.  

empty

 

OpenDistributePriorityV2.0Request / RecipientEmail

optional

This contains the email address or is blank

string

valid email address  

OpenDistributePriorityV2.0Request / AllowNonCleansedFacilityAddr

optional

Allows option to not cleanse Facility Address.  If selected, may result in an undeliverable package.

boolean

default=false

OpenDistributePriorityV2.0Request / HoldForManifest

optional

Restricted use. Holds manifest record for possible inclusion in SCAN request.

string

Enumerations:

Y
N

OpenDistributePriorityV2.0Request / CommercialPrice

optional

For future use.

boolean

Default=false

OpenDistributePriorityV2.0Request  / Container

optional

Use to specify special containers or container attributes that may affect postage; otherwise, leave blank.

 

Specifically this is used to indicate various flat and regional rate options for Priority Mail, otherwise the API will assume "simple". Needed to assign an appropriate RDC and to ensure the proper 3 digit service type code is included in the barcode.


For example: <Container>VARIABLE</Container> 

string

Enumerations=

VARIABLE
FLAT RATE ENVELOPE

LEGAL FLAT RATE ENVELOPE

PADDED FLAT RATE ENVELOPE
GIFT CARD FLAT RATE ENVELOPE

SM FLAT RATE ENVELOPE

WINDOW FLAT RATE ENVELOPE

FLAT RATE BOX

SM FLAT RATE BOX
MD FLAT RATE BOX

LG FLAT RATE BOX

REGIONALRATEBOXA

REGIONALRATEBOXB

REGIONALRATEBOXC
RECTANGULAR
NONRECTANGULAR

 

default=VARIABLE

OpenDistributePriorityV2.0Request  / Size

optional

Defined as follows:

 

REGULAR: all package dimensions are under 12’’;

LARGE: any package dimension is greater than 12’’

 

For example: <Size>REGULAR</Size> 

string



Enumerations=

REGULAR

LARGE

OpenDistributePriorityV2.0Request  / Width

optional

Value must be numeric. Units are inches. Required when Size is LARGE.

For example: <Width>5.5</Width> 

decimal

minExclusive=0.0
totalDigits=10  

OpenDistributePriorityV2.0Request  / Length

optional

Value must be numeric. Units are inches. Required when Size is LARGE.

For example: <Length>11</Length> 

decimal

minExclusive=0.0
totalDigits=10  

OpenDistributePriorityV2.0Request  / Height

optional

Value must be numeric. Units are inches. Required when Size is LARGE.

For example: <Height>11</Height> 

decimal

minExclusive=0.0
totalDigits=10  

OpenDistributePriorityV2.0Request  / Girth

optional

Value must be numeric. Units are inches. Girth is only required when Container = ‘NONRECTANGULAR’ or ‘VARIABLE’ and Size=’LARGE’


For example: <Girth>11</Girth> 

decimal

minExclusive=0.0
totalDigits=10  

OpenDistributePriorityV2.0Request  / ReturnCommitments

optional

Indicates if commitment information should be returned.

boolean

default=false

OpenDistributePriorityV2.0Request  / Content

optional

Special Contents of package

(group)

 

OpenDistributePriorityV2.0Request  / Content / ContentType

required once – if content included

Use to specify ContentType.  Available types are:

 

ContentType

HAZMAT

LIVES

PERISHABLE

FRAGILE

 

Required if LIVES.

 

Example: < ContentType >LIVES</ ContentType >

 

Note:  USPS-produced packaging, including Flat Rate and Regional Rate, cannot be used to ship live animals.  Error response will be returned.

string

Enumerations=

HAZMAT 

LIVES

PERISHABLE

FRAGILE

OpenDistributePriorityV2.0Request  / Content / ContentDescription

optional

Description. Required if LIVES.

string

Enumerations:

BEES

DAYOLDPOULTRY

ADULTBIRDS

OTHER

 

Sample Request

Test XML Request:

https://secure.shippingapis.com/ShippingAPI.dll?API=OpenDistributePriorityV2Certify&XML=<?xml version="1.0" encoding="UTF-8" ?>

<OpenDistributePriorityCertifyV2.0Request USERID="xxx">

    <Revision/>

    <ImageParameters>

        <ImageParameter/>

    </ImageParameters>

    <PermitNumber>1</PermitNumber>

    <PermitIssuingPOZip5>18701</PermitIssuingPOZip5>

    <FromName>John Doe</FromName>

    <FromFirm>XYZ Corporation</FromFirm>

    <FromAddress1>Ste 501</FromAddress1>

    <FromAddress2>7 North Wilkes Barre Blvd</FromAddress2>

    <FromCity>Wilkes Barre</FromCity>

    <FromState>PA</FromState>

    <FromZip5>18702</FromZip5>

    <FromZip4/>

    <POZipCode>18701</POZipCode>

    <ToFacilityName>Fairfax Post Office</ToFacilityName>

    <ToFacilityAddress1/>

    <ToFacilityAddress2>10660 Page Ave</ToFacilityAddress2>

    <ToFacilityCity>Fairfax</ToFacilityCity>

    <ToFacilityState>VA</ToFacilityState>

    <ToFacilityZip5>22030</ToFacilityZip5>

    <ToFacilityZip4/>

    <ToFacilityPOBoxFlag>false</ToFacilityPOBoxFlag>

    <FacilityType>DDU</FacilityType>

    <MailClassEnclosed>OTHER</MailClassEnclosed>

    <MailClassOther>Free Samples</MailClassOther>

    <WeightInPounds>22</WeightInPounds>

    <WeightInOunces>10</WeightInOunces>

    <ImageType>TIF</ImageType>

    <SeparateReceiptPage>false</SeparateReceiptPage>

    <AllowNonCleansedFacilityAddr>false</AllowNonCleansedFacilityAddr>

    <HoldForManifest>N</HoldForManifest>

    <CommercialPrice>N</CommercialPrice>

    <ReturnCommitments>true</ReturnCommitments>

</OpenDistributePriorityCertifyV2.0Request>

Response Descriptions

Tag Name

Occurs

Description

Type

OpenDistributePriorityV2.0Response

required once

The OpenDistributePriorityV2.0Response XML document is sent in response to an OpenDistributePriorityV2.0Request.  

 

Certify response:

The OpenDistributePriorityV2CertifyResponse XML document is sent in response to an OpenDistributePriorityV2CertifyRequest.  

 

(group)

OpenDistributePriorityV2.0Response / OpenDistributePriorityNumber

required once

Open and Distribute ID Number (PIC #)  

string

OpenDistributePriorityV2.0Response / OpenDistributePriorityLabel

optional

Open and Distribute Shipping Label (not returned when Image Type is None in the request).  

base64Binary

OpenDistributePriorityV2.0Response / OpenDistributePriorityReceipt

optional

Open and Distribute Customer Online Record (returned only when SeparateReceiptPage is true in the request). This tag is returned only if the <SeparateReceiptPage> tag was set to "true" in the request. Otherwise the Customer Online Record is contained within the label image and the <OpenDistributePriorityV2Receipt> tag is NOT present in the response. 

base64Binary

OpenDistributePriorityV2.0Response / ToFacilityName

required once

Drop shipment facility name from the request  

string

OpenDistributePriorityV2.0Response / ToFacilityAddress1

required once

Standardized facility address line 1  

string

OpenDistributePriorityV2.0Response / ToFacilityAddress2

required once

Standardized facility address line 2  

string

OpenDistributePriorityV2.0Response / ToFacilityCity

required once

Standardized facility city  

string

OpenDistributePriorityV2.0Response / ToFacilityState

required once

Standardized facility state  

string

OpenDistributePriorityV2.0Response / ToFacilityZip5

required once

Standardized facility ZIP code  

string

OpenDistributePriorityV2.0Response / ToFacilityZip4

required once

Standardized facility ZIP+4 extension  

string

OpenDistributePriorityV2.0Response / ToFacilityPOBOXFlag

Optional

Indicates that the ToFacility address is a PO Box.

boolean

OpenDistributePriorityV2.0Response / Postage

required once

Postage amount

string

OpenDistributePriorityV2.0Response / Zone

required once

Postal Zone. Indicates the number of postal rate zones between the origin and destination ZIP codes.  

string

OpenDistributePriorityV2.0Response / Commitment

optional

Returned if ReturnCommitments is true in the request.

(group)

OpenDistributePriorityV2.0Response / Commitment / CommitmentName

optional

Commitment name such as 1-day, 2-day, 3-day, Military, DPO

String

OpenDistributePriorityV2.0Response / Commitment / ScheduledDeliveryDate

optional

Date in the YYYY-MM-DD format.

date

 

Sample Response

Test XML Response:

<?xml version="1.0" encoding="UTF-8" ?>

<OpenDistributePriorityCertifyV2.0Response>

  <OpenDistributePriorityNumber>420220309155805213907020971523</OpenDistributePriorityNumber>

  <OpenDistributePriorityLabel>JVBERi0xLjICBvYmoN<!--truncated--> </OpenDistributePriorityLabel>

  <ToFacilityName>Fairfax Post Office</ToFacilityName>

  <ToFacilityAddress1/>

  <ToFacilityAddress2>10660 PAGE AVE</ToFacilityAddress2>

  <ToFacilityCity>FAIRFAX</ToFacilityCity>

  <ToFacilityState>VA</ToFacilityState>

  <ToFacilityZip5>22030</ToFacilityZip5>

  <ToFacilityZip4>4098</ToFacilityZip4>

  <Postage>26.25</Postage>

  <Zone>3</Zone>

          <Commitment>

            <CommitmentName>3-Day</CommitmentName>

            <ScheduledDeliveryDate>2013-07-29</ScheduledDeliveryDate>

    </Commitment>

</OpenDistributePriorityCertifyV2.0Response >

Error Responses

Error conditions are handled at the main XML document level.  When parsing, it is best to check for an error document first before checking for good data.  Error documents have the following format:

<Error>

<Number></Number>

<Source></Source>

<Description></Description>

<HelpFile></HelpFile>

<HelpContext></HelpContext>

</Error>

Where:

·         Number = the error number generated by the Web Tools server.

·         Source = the component and interface that generated the error on the Web Tools server.

·         Description = the error description.

·         HelpFile = [reserved for future use].

·         HelpContext = [reserved for future use].

Errors that are further down in the hierarchy also follow the above format.

An <Error> element may be returned at the top (response) level if there is a problem with the syntax of the request, or if a system error occurs.

 

If you need assistance with an error response, contact our Internet Customer Care Center uspstechnicalsupport@mailps.custhelp.com.