Open and Distribute Labels

 

USPS Web Tools™

Application Programming Interface

Reference

Document Version 3.0 (01/26/2014)

 

 

 

United States Postal Service Logo
 

 

 

 



To Our Customers

In registering for use of the USPS Web Tools™ (Web Tools), you received a user ID that will allow you to begin sending calls to the server when you are ready.  Any additional information or contact with you will occur as indicated on the registration form, please return to the Web Tools eCommerce API Technical Guides site for the most recent documentation for any of the Web Tools.

If you require technical support, contact the USPS Internet Customer Care Center (ICCC).  This office is staffed as follows:

 

E-mail address:  uspstechnicalsupport@mailps.custhelp.com

Telephone: 1-800-344-7779

 

USPS Customer Commitment

The United States Postal Service fully understands the importance of providing information and service anytime day or night to your Internet and e-commerce customers.  For that reason, the USPS is committed to providing 24 x 7 service from our Web Tools servers, 365 days a year.

Registered Trademarks

Priority Mail, Priority Mail Flat Rate, Priority Mail International, Priority Mail Regional Rate, Global Express Mail, Global Express Guaranteed, Global Priority Mail, Parcel Post, Parcel Select, First-Class Mail, USPS, USPS Web Tools, and ZIP + 4 are registered trademarks of the U.S. Postal Service.

Priority Mail Express, Priority Mail Express 1-Day, Priority Mail Express 2-Day, Priority Mail Express 3-Day, Priority Mail Express DPO, Priority Mail Express International, Priority Mail Express Intl, Priority Mail Express Military, Priority Mail Express Offshore, Priority Mail 1-Day, Priority Mail 2-Day, Priority Mail 3-Day, Priority Mail DPO, Priority Mail Intl, Priority Mail Military, Priority Mail Offshore, Signature Confirmation, Standard Post, USPS Tracking, ZIP, and ZIP Code are trademarks of the U.S. Postal Service.

Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.

Adobe Acrobat and Adobe Reader are trademarks of Adobe Systems Incorporated.

DUNS is a registered trademark of Dun & Bradstreet.

ãCopyright 2013 United States Postal Service


 

Table of Contents

1       Introduction. 5

2       Open / Distribute Priority API 5

2.1           Open / Distribute Priority Request 6

2.1.1     API Signature. 7

2.1.2     Request Parameters. 8

2.1.3     Request Example. 12

2.2           Open / Distribute Priority Response. 15

2.2.1     Response Parameters. 15

2.2.2     Label Diagram.. 17

2.2.3     Tagged Label Diagram.. 18

2.2.4     Response Example. 19

 


1     Introduction

Express Mail Open and Distribute and Priority Mail Open and Distribute provide alternatives for mailers who want to expedite the transportation of shipments of other classes of mail to mail processing facilities and destination delivery units (DDU). Mailers prepare the mailings according to standards for the enclosed class of mail; enclose the mail in USPS Priority Mail approved container for expedited service as either Express Mail Open and Distribute or Priority Mail Open and Distribute.  The mailings are presented at a Business Mail Entry Unit (BMEU) or authorized location by the critical entry time for USPS shipment.

For additional information about Open and Distribute, please refer to the Domestic Mail Manual (DMM®) 705.16 at http://pe.usps.com/.

This document contains a Reference Guide to the Open and Distribute Labels APIs.  See the Developer’s Guide to Web Tools APIs 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.

2     Open / Distribute Priority API

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

 

2.1    Open / Distribute Priority Request

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,55, 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.

 

Content Information

Facility

ZIP/CRIDs

Discount

CIN Group

Facility

NASS

Address

City

State

ZIP

130-136, 140-168, 260-266, 439-449

BMC

Standard/Flats

PITTSBURGH BMC

15Z

300 BRUSH CREEK RD

WARRENDALE

PA

150951002

440-441

SCF

Standard/Irregular Parcels

CLEVELAND

440

2400 ORANGE AVE RM 30

CLEVELAND

OH

441019701

130-136, 140-168, 260-266, 439-449

BMC

Standard/Letters

PITTSBURGH BMC

15Z

300 BRUSH CREEK RD

WARRENDALE

PA

150951002

440-441

SCF

Standard/Machinable Parcels

CLEVELAND

440

2400 ORANGE AVE RM 30

CLEVELAND

OH

441019701

 

Contact the USPS Internet Customer Care Center (ICCC) for additional information on using FAST for Open and Distribute destinations.

 

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

 


 

2.1.2     Request Parameters

Tag Name

Occurs

Description

Type

Validation

OpenDistributePriorityV2.0Request

required once

API=OpenDistributePriorityV2 This API produces a Priority Mail Open and Distribute label complete with barcode and receipt, with optional Permit imprint. Contact ICCC for permission to invoke this API.
Internet Customer Care Center (ICCC)
E-mail:
uspstechsupport@esecurecare.net
Telephone: 1-800-344-7779

(group)

 

OpenDistributePriorityV2.0Request / @USERID

required

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

NMTOKEN

 

OpenDistributePriorityV2.0Request / @PASSWORD

optional

For backward compatibility; not validated. 

NMTOKEN

 

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}

pattern=

OpenDistributePriorityV2.0Request / ImageParameters

optional

For future use.

(group)

 

OpenDistributePriorityV2.0Request / ImageParameters / ImageParameter

required

For future use. Required on request, leave blank.

string

 

OpenDistributePriorityV2.0Request / PermitNumber

optional

Input Permit number provided by your local post office.  

string

whiteSpace=collapse
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

whiteSpace=collapse
pattern=\d{5}  

OpenDistributePriorityV2.0Request / FromName

required once

Name of sender.  

string

minLength=1
maxLength=32
whiteSpace=collapse  

OpenDistributePriorityV2.0Request / FromFirm

required once

Company name.  

string

minLength=0
maxLength=32
whiteSpace=collapse  

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=32
whiteSpace=collapse  

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=32
whiteSpace=collapse  

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=21
whiteSpace=collapse  

OpenDistributePriorityV2.0Request / FromState

required once

Use only official USPS state name abbreviations.  

string

whiteSpace=collapse
pattern=\w{2}  

OpenDistributePriorityV2.0Request / FromZip5

required once

Correct 5-digit ZIP Code.  

string

whiteSpace=collapse
pattern=\d{5}  

OpenDistributePriorityV2.0Request / FromZip4

required once

Last four digits of a complete ZIP+4 code.  

string

minLength=0
whiteSpace=collapse
pattern=\d{4}
pattern=  

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
whiteSpace=collapse
pattern=\d{5}
pattern=  

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
whiteSpace=collapse  

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
whiteSpace=collapse  

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
whiteSpace=collapse  

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=21
whiteSpace=collapse  

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
whiteSpace=collapse
pattern=\w{2}
pattern=  

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
whiteSpace=collapse
pattern=\d{5}
pattern=  

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
whiteSpace=collapse
pattern=\d{4}
pattern=  

OpenDistributePriorityV2.0Request / ToFacilityPOBoxFlag

optional

Indicates that the ToFacility address is a PO Box.

boolean

default=false

OpenDistributePriorityV2.0Request / FacilityType

required once

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

string

whiteSpace=collapse
enumeration=DDU
enumeration=SCF
enumeration=BMC
enumeration=ADC
enumeration=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

whiteSpace=collapse
enumeration=Letters
enumeration=Flats
enumeration=Parcels
enumeration=Mixed
enumeration=Other  

OpenDistributePriorityV2.0Request / MailClassOther

optional

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

string

minLength=0
maxLength=21
whiteSpace=collapse  

OpenDistributePriorityV2.0Request / WeightInPounds

optional

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

decimal

minInclusive=0
maxInclusive=70
whiteSpace=collapse  

OpenDistributePriorityV2.0Request / WeightInOunces

optional

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

integer

maxInclusive=1120
minInclusive=0
whiteSpace=collapse  

OpenDistributePriorityV2.0Request / ImageType

required once

The type of label image desired.  

string

whiteSpace=collapse
enumeration=TIF
enumeration=PDF
enumeration=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
whiteSpace=collapse  

OpenDistributePriorityV2.0Request / LabelDate

optional

This tag allows the end-user to post-date the label up to four days in advance. The package should not be shipped until the ship date requested.  

string

minLength=0
whiteSpace=collapse
pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?
pattern=  

OpenDistributePriorityV2.0Request / CustomerRefNo

optional

For future use.  

empty

 

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

enumeration=Y
enumeration=N

OpenDistributePriorityV2.0Request / CommercialPrice

optional

For future use.

boolean

Default=N

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

Type of content

string

enumeration=HAZMAT
enumeration=LIVES

OpenDistributePriorityV2.0Request  / Content / ContentDescriptor

optional

Description. Required if LIVES.

string

enumeration=Bees
enumeration=DayOldPoultry

enumeration=AdultBirds

enumeration=Other

OpenDistributePriorityV2.0CertifyRequest

required once

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.  

(alias)

 

 

 

2.1.3     Request Example

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

</OpenDistributePriorityV2.0Request>

 

 

 

 

 


 

2.2    Open / Distribute Priority Response

2.2.1     Response Parameters

Tag Name

Occurs

Description

Type

Validation

OpenDistributePriorityV2.0Response

required once

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

(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 ImageType 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 / 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

 

OpenDistributePriorityV2.0CertifyResponse

required once

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

(alias)

 

2.2.2     Label Diagram

2.2.3     Tagged Label Diagram

 

2.2.4     Response Example

<?xml version="1.0"?>

<OpenDistributePriorityV2.0Response>

  <OpenDistributePriorityNumber>420220309155805213907020971523</OpenDistributePriorityNumber>

  <OpenDistributePriorityLabel>JVBERi0xLjINCjUgMCBvYmoNCjw8DQovVHlwZSAvWE9iamVjd<!--38031 suppressed>= </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>

 

</OpenDistributePriorityV2.0Response>