Hold For Pickup

Express, Priority and First Class

 

 

 

USPS Web Tools™

Application Programming Interface

Reference

Document Version 3.0 (01/28/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:

  • Monday through Friday from 8:00 a.m. to 8:30 p.m. Eastern Time 
  • Saturdays from 8:00 a.m. to 6:00 p.m. Eastern Time 
  • Sunday and Postal Holidays - Closed except for the following Holidays: Martin Luther King; President's Day; Columbus Day; &  Veteran's Day with hours from 9:00 a.m. to 6:00 p.m. ET.

 

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

1.1           Error Responses. 7

2       Hold For Pickup Facility Information API 8

2.1           Hold For Pickup Facility Info Request 8

2.1.1     API Signature. 8

2.1.2     Request Parameters. 8

2.1.3     Request Example. 9

2.2           Hold For Pickup Facility Info Response. 10

2.2.1     Response Parameters. 10

4.1.1     Response Example. 11

3       Hold For Pickup Express Mail Label API 13

3.1           Hold For Pickup Express Request 13

3.1.1     API Signature. 13

3.1.2     Request Parameters. 13

3.1.3     Request Example. 26

3.2           Hold For Pickup Express Response. 28

3.1.1     Response Parameters. 28

3.1.2     Response Example. 31

3.1.3     Tagged Label Diagram.. 33

4       Hold For Pickup Priority Mail Label API 36

4.1           Hold For Pickup Priority Request 36

4.1.1     API Signature. 36

4.1.2     Request Parameters. 36

4.1.3     Request Example. 49

4.2           Hold For Pickup Priority Response. 51

4.1.1     Response Parameters. 51

4.1.2     Response Example. 54

4.1.3     Sample Label 55

5       Hold For Pickup First Class Mail Label API 57

5.1           Hold For Pickup First Class Request 57

5.1.1     API Signature. 57

5.1.2     Request Parameters. 58

5.1.3     Request Example. 69

5.2           Hold For Pickup First Class Response. 71

5.1.1     Response Parameters. 71

5.1.2     Response Example. 74

5.1.3     Sample Label 75

1    Introduction

Priority Mail Express Hold For Pickup service is available for pickup at approximately 31,000 USPS locations. Shipments are available for pickup by the recipient or a designee at the designated Hold For Pickup location by either 10 a.m., noon, or 3 p.m., based on the Priority Mail Express service standard. 

Priority Mail Express Hold For Pickup shipments are sent to a designated Hold For Pickup location -- such as a Post Office -- where the shipment is picked up within five calendar days. Each shipment is identified with the name and address of the sender, the name and address of the recipient, and the name and address of the designated Hold For Pickup location on the address label. 

Priority Mail Express Hold For Pickup service lets customers pick up shipments when it is convenient for them, with the assurance that their shipments are held safely and securely. Automatic notifications via e-mail or SMS text messaging are also available, using the USPS Web Tools Express Mail Hold For Pickup API. 

Note: Priority Mail Express Hold For Pickup is not available for International or APO/FPO destinations.

For additional information about Hold For Pickup, please refer to the Domestic Mail Manual (DMM®).

This document contains a Reference Guide to the Hold For Pickup 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.


 

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


 

2    Hold For Pickup Facility Information API

2.1       Hold For Pickup Facility Info Request

2.1.1     API Signature

Scheme

Host

Path

API

XML

http://

production.shippingapis.com

/ShippingAPI.dll

?API=HFPFacilityInfo

&XML=(see below)

 

2.1.2     Request Parameters

Tag Name

Occurs

Description

Type

Validation

HFPFacilityInfoRequest

required once

API=HFPFacilityInfo (Hold-For-Pickup Facility Information API)
This API will list US Postal Service Facilities where Hold-For-Pickup service is available. The response includes facilities based on ZIP code (five or nine digit) or City/State up to a maximum number of locations. The facility address or facility ID may be used as the destination in subsequent Hold-For-Pickup Label requests.  

(group)

 

HFPFacilityInfoRequest / @USERID

required

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

NMTOKEN

 

HFPFacilityInfoRequest / @PASSWORD

optional

For backward compatibility; not validated. 

string

 

HFPFacilityInfoRequest / PickupCity

required once

Either City/State or ZIP code must be specified. When only city and state are provided, all pickup facilities with addresses within that city and state will be returned.


For example: <PickupCity>Boston</PickupCity> 

string

minLength=0
maxLength=23
whiteSpace=collapse  

HFPFacilityInfoRequest / PickupState

required once

Either City/State or ZIP code must be specified.


For example: <PickupState>MA</PickupState> 

string

minLength=0
pattern=\w{2}
pattern=  

HFPFacilityInfoRequest / PickupZIP

required once

Either City/State or ZIP code must be specified. When PickupZIP provided without PickupZIP4, all pickup facilities that service that ZIP code are returned.


For example: <PickupZIP>02111</PickupZIP> 

string

minLength=0
pattern=\d{5}
pattern=  

HFPFacilityInfoRequest / PickupZIP4

required once

If PickupZIP is specified, then PickupZIP4 may also be specified. This will match to a single pickup facility with the given nine-digit ZIP code.


For example: <PickupZIP4>9998</PickupZIP4> 

string

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

HFPFacilityInfoRequest / Service

optional

For future use.  May be omitted.

string

default=EXPRESS
enumeration=EXPRESS

 

2.1.3     Request Example

<HFPFacilityInfoRequest USERID="xxx">

    <PickupCity />

    <PickupState/>

    <PickupZIP>33952</PickupZIP>

    <PickupZIP4 />

    <Service />

</HFPFacilityInfoRequest>

 

2.2   Hold For Pickup Facility Info Response

2.2.1     Response Parameters

Tag Name

Occurs

Description

Type

Validation

HFPFacilityInfoResponse

required once

The XML document returned in response to a HFPFacilityInfoRequest. Alternatively, the Web Tools Error document may be returned if the request could not be completed.  

(group)

 

HFPFacilityInfoResponse / PickupCity

required once

The criteria used to obtain the facility list is echoed back here. Either City/State or ZIP code (five or nine digit).  

string

 

HFPFacilityInfoResponse / PickupState

required once

The criteria used to obtain the facility list is echoed back here. Either City/State or ZIP code (five or nine digit).  

string

 

HFPFacilityInfoResponse / PickupZIP

required once

The criteria used to obtain the facility list is echoed back here. Either City/State or ZIP code (five or nine digit).  

string

 

HFPFacilityInfoResponse / PickupZIP4

required once

The criteria used to obtain the facility list is echoed back here. Either City/State or ZIP code (five or nine digit).  

string

 

HFPFacilityInfoResponse / Service

optional

Echoed back from request.  

string

 

HFPFacilityInfoResponse / Facility

optional repeating up to 50 times

Facility addresses are returned in no particular order. If none are returned, then no facilities matched the criteria given in the request. If there are more than 50 facilities found, the first 50 will be returned along with a maximum-exceeded advisory in the LogMessage tag.  

(group)

 

HFPFacilityInfoResponse / Facility / FacilityID

required once

ID of Pickup Facility. This value is used in the request for a Hold-For-Pickup Express or Priority Mail Label.  

string

 

HFPFacilityInfoResponse / Facility / FacilityName

required once

Name of Pickup Facility  

string

 

HFPFacilityInfoResponse / Facility / FacilityAddress

required once

Pickup Facility Address  

string

 

HFPFacilityInfoResponse / Facility / FacilityCity

required once

Pickup Facility City  

string

 

HFPFacilityInfoResponse / Facility / FacilityState

required once

Pickup Facility State  

string

 

HFPFacilityInfoResponse / Facility / FacilityZIP

required once

Pickup Facility ZIP Code  

string

 

HFPFacilityInfoResponse / Facility / FacilityZIP4

required once

Pickup Facility ZIP Code+4  

string

 

HFPFacilityInfoResponse / Facility / Has10amCommitment

required once

Indicative of facility's hold-for-pickup availability. A value of "true" indicates packages can be available for pickup at 10:00 am local time.  

boolean

 

HFPFacilityInfoResponse / LogMessage

optional

A text message for integrators of this API. It may contain additional information about this particular request/response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.  

string

 

 

4.1.1     Response Example

 

 <HFPFacilityInfoResponse>

    <PickupCity/>

    <PickupState/>

    <PickupZIP>33952</PickupZIP>

    <PickupZIP4/>

    <Facility>

        <FacilityID>1438805</FacilityID>

        <FacilityName>PORT CHARLOTTE BRANCH</FacilityName>

        <FacilityAddress>3740 TAMIAMI TRL</FacilityAddress>

        <FacilityCity>PORT CHARLOTTE</FacilityCity>

        <FacilityState>FL</FacilityState>

        <FacilityZIP>33952</FacilityZIP>

        <FacilityZIP4>9998</FacilityZIP4>

        <Has10amCommitment>false</Has10amCommitment>

    </Facility>

    <Facility>

        <FacilityID>1378061</FacilityID>

        <FacilityName>PORT CHARLOTTE ANNEX</FacilityName>

        <FacilityAddress>18100 PAULSON DR</FacilityAddress>

        <FacilityCity>PORT CHARLOTTE</FacilityCity>

        <FacilityState>FL</FacilityState>

        <FacilityZIP>33954</FacilityZIP>

        <FacilityZIP4>9998</FacilityZIP4>

        <Has10amCommitment>false</Has10amCommitment>

    </Facility>

</HFPFacilityInfoResponse>

 

3        Hold For Pickup Express Mail Label API

3.1       Hold For Pickup Express Request

3.1.1     API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=HoldForPickupExpress

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=HoldForPickupExpressCertify

&XML=(see below)

 

3.1.2     Request Parameters

Tag Name

Occurs

Description

Type

Validation

HoldForPickupExpressRequest

required once

API=HoldForPickupExpress (Hold-For-Pickup Express Mail Label API)
This API can generate an Priority Mail Express Hold-For-Pickup label with a unique tracking number which is manifested with the customer-contact details provided in the request. When the package arrives at the destination Hold-For-Pickup facility, the customer is notified according to the indicated preference. The individual picking up the package will be required to present identification that agrees with the recipient information provided in the request as well as the last four digits of the tracking number. Facility addresses can be obtained interactively at USPS.com (Locate a Post Office) or programmatically via the HFP Facility Info API. 

(group)

 

HoldForPickupExpressRequest / @USERID

required

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

NMTOKEN

 

HoldForPickupExpressRequest / @PASSWORD

optional

For backward compatibility; not validated. 

string

 

HoldForPickupExpressRequest / Option

required once

For future use.  

empty

 

HoldForPickupExpressRequest / Revision

optional

In this API use a value of 2 to trigger new functionality.

For example: <Revision>2</Revision>

string

minLength=0
pattern=\d{1}
pattern=  

HoldForPickupExpressRequest / EMCAAccount

required once

For future use.  

string

 

HoldForPickupExpressRequest / EMCAPassword

required once

For future use.  

string

 

HoldForPickupExpressRequest / ImageParameters

required once

For future use.  

empty

 

HoldForPickupExpressRequest / FromFirstName

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for first and last names combined.


For example: <FromFirstName>MT</FromFirstName> 

string

minLength=0

maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / FromLastName

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for first and last names combined.


For example: <FromLastName>MARTIAN</FromLastName> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / FromFirm

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for firm name.


For example: <FromFirm>USPS</FromFirm> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / FromAddress1

required once

From address line 1. Use this tag for an apartment or suite number.


For example: <FromAddress1>STE 150</FromAddress1>

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / FromAddress2

required once

From address line 2.

For example: <FromAddress2>6600 ROCKLEDGE DR</FromAddress2> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / FromCity

required once

From city.


For example: <FromCity>BETHESDA</FromCity> 

string

minLength=1
maxLength=23
whiteSpace=collapse  

HoldForPickupExpressRequest / FromState

required once

From state.


For example: <FromState>MD</FromState> 

string

whiteSpace=collapse
pattern=\w{2}  

HoldForPickupExpressRequest / FromZip5

required once

From ZIP code.


For example: <FromZip5>210817</FromZip5> 

string

whiteSpace=collapse
pattern=\d{5}  

HoldForPickupExpressRequest / FromZip4

required once

From ZIP+4 extension.


For example: <FromZip4/> 

string

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

HoldForPickupExpressRequest / FromPhone

required once

From Phone #. 10 digits required (including area code), with no punctuation.


For example: <FromPhone>5745556191</FromPhone> 

string

whiteSpace=collapse
pattern=\d{10}  

HoldForPickupExpressRequest / FromContactPreference

required once

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


For example:

<FromContactPreference>EMAIL

</FromContactPreference> 

string

default=EMAIL
whiteSpace=collapse
enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupExpressRequest / FromContactMessaging

required once

This contains the email address or the text messaging address or is blank depending on the FromContactPreference tag. If the EMAIL or SMS enumeration is used in FromContactPreference, this value must be a syntactically-valid e-mail address. If WAIVED is used, this value must be blank.


For example: <FromContactMessaging>user@anydomain.gov

</FromContactMessaging> 

string

maxLength=64
whiteSpace=collapse
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupExpressRequest / POZipCode

required once

ZIP Code of Post Office or collection box where item is mailed. Specify when different than FromZip5; otherwise, may be left blank.


For example: <POZipCode/> 

string

whiteSpace=collapse
pattern=\d{5}
pattern=\d{0}  

HoldForPickupExpressRequest / ToFirstName

required once

This information pertains to the recipient of the package, not the pickup destination. Maximum length: 26 characters for both names.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToFirstName>John</ToFirstName>

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / ToLastName

required once

This information pertains to the recipient of the package, not the pickup destination. Maximum length: 26 characters for both names.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToLastName>Smith</ToLastName> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / ToFirm

required once

This information pertains to the recipient of the package, not the pickup destination. Specify name of firm or leave blank.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToFirm>ABC CORPORATION</ToFirm> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / ToAddress1

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient address line 1 contains an apartment or suite number.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToAddress1/> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / ToAddress2

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient address line 2 contains the street address.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToAddress2>1234 MAIN ST</ToAddress2> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupExpressRequest / ToCity

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient city.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToCity>ANYTOWN</ToCity> 

string

minLength=1
maxLength=23
whiteSpace=collapse  

HoldForPickupExpressRequest / ToState

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient state.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToState>MN</ToState> 

string

whiteSpace=collapse
pattern=\w{2}  

HoldForPickupExpressRequest / ToZip5

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient ZIP code.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToZip5>12345</ToZip5> 

string

whiteSpace=collapse
pattern=\d{5}  

HoldForPickupExpressRequest / ToZip4

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient ZIP+4 extension.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToZip4/> 

string

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

HoldForPickupExpressRequest / 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

default=EMAIL
whiteSpace=collapse
enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupExpressRequest / ToContactMessaging

required once

This contains the email address or the text messaging address or is blank depending on the ToContactPreference tag. If the EMAIL or SMS enumeration is used in ToContactPreference, 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
whiteSpace=collapse
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupExpressRequest / FacilityID

required once

A FacilityID obtained from the Hold-For-Pickup Facility Information API is required. FacilityID specifies the package destination; that is, the USPS facility where the package will be picked up.


For example: <FacilityID>210454648</FacilityID>  

string

 

HoldForPickupExpressRequest / WeightInOunces

required once

Package weight. Items must weigh 70 pounds or less.


For example: <WeightInOunces>80</WeightInOunces> 

integer

default=0
minInclusive=0
maxInclusive=1170  

HoldForPickupExpressRequest / FlatRate

optional

Deprecated. See "Container" tag.  

boolean

default=false

HoldForPickupExpressRequest / CommercialPrice

optional

Indicates if commercial-base price should be returned. For commercial-base price eligibility, please reference the Domestic Mail Manual at http://pe.usps.com/.

 

For example: <CommercialPrice>False

</CommercialPrice>

boolean

default=false 

HoldForPickupExpressRequest / SeparateReceiptPage

optional

Label and Customer Online Record Printed on two separate pages. Enter "true" if you want the shipping label and online customer record printed on two separate pages or "false" if you want them printed on the same single page.


For example:

<SeparateReceiptPage>true</SeparateReceiptPage>  

boolean

default=false
 

HoldForPickupExpressRequest / ImageType

required once

Label Image Type.


For example: <ImageType>PDF</ImageType>  

string

whiteSpace=collapse
enumeration=PDF
enumeration=TIF
enumeration=NONE  

HoldForPickupExpressRequest / 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:

 

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

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

 

For example:

<LabelDate>01/10/2010</LabelDate>

string

whiteSpace=collapse

minLength=0
pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?
pattern=\d{1,2}-\w{3}-\d\d(\d\d)?
pattern=\d{0}  

HoldForPickupExpressRequest / LabelTime

optional

Time Package Will Be Mailed. Time may be midnight (00:00) to 23:59.  Enter the time in the format: HH:MM such as 13:30.


For example:
<LabelTime>15:00</LabelTime>

string

whiteSpace=collapse

minLength=0
pattern=\d{1,2}/:d{2}
pattern=\d{0}  

HoldForPickupExpressRequest / CustomerRefNo

optional

User-assigned number for caller's use. Appears on label.


For example: <CustomerRefNo>123-ABCD-56789F</CustomerRefNo> 

string

minLength=0
maxLength=30
whiteSpace=collapse  

HoldForPickupExpressRequest / SenderName

optional

Name of E-mail Sender. If the HoldForPickupExpressRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. SenderName, if specified, is used to sign the e-mail.


For example: <SenderName/>  

string

minLength=0
whiteSpace=collapse
maxLength=50  

HoldForPickupExpressRequest / SenderEMail

optional

E-mail Address of Sender. A single valid e-mail address must be used. If the HoldForPickupExpressRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. If SenderEMail is specified, then the e-mail is cc:'d to this address. It also appears as contact information in the body of the message.


For example: <SenderEMail></SenderEMail>  

string

whiteSpace=collapse
maxLength=100
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupExpressRequest / RecipientName

optional

Name of E-mail Recipient. If the HoldForPickupExpressRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. RecipientName, if specified, is used in the message salutation.


For example: <RecipientName/> 

string

minLength=0
whiteSpace=collapse
maxLength=50  

HoldForPickupExpressRequest / RecipientEMail

optional

E-mail Address of Recipient. A single valid e-mail address must be used. If this tag is specified, an e-mail is created and sent to this recipient address when the label is created. This e-mail contains the tracking number and the scheduled shipment date. This tag is optional but it is the only tag required to activate the e-mail feature; SenderName, SenderEMail, and RecipientName are always optional.


For example: <RecipientEMail></RecipientEMail> 

string

whiteSpace=collapse
maxLength=100
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupExpressRequest / HoldForManifest

optional

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

string

enumeration=Y
enumeration=N

HoldForPickupExpressRequest / InsuredAmount

optional

Use this tag for entering an insurance amount, if applicable.

For example: <InsuredAmount>100.00</InsuredAmount> 

decimal

default=0
minInclusive=0
maxInclusive=9999.99
totalDigits=8
whiteSpace=collapse  

HoldForPickupExpressRequest / Container

optional

Use to specify special containers or container attributes that may affect postage; otherwise, leave blank.  Required when <Revision>=’2’.

 

Note: RECTANGULAR or NONRECTANGULAR must be indicated when <Size>LARGE</Size>.


For example: <Container>RECTANGULAR</Container> 

string

whiteSpace=collapse
enumeration=VARIABLE

enumeration=RECTANGULAR
enumeration=NONRECTANGULAR

enumeration=FLAT RATE ENVELOPE

enumeration=LEGAL FLAT RATE ENVELOPE

enumeration=PADDED FLAT RATE ENVELOPE

enumeration=FLAT RATE BOX

HoldForPickupExpressRequest /

Size

optional

Required when <Revision>=’2’. Defined as follows:

 

REGULAR: all package dimensions are under 12’’;

LARGE: any package dimension is greater than 12’’

 

For example: <Size>REGULAR</Size> 

string

whiteSpace=collapse
enumeration=LARGE
enumeration=REGULAR

HoldForPickupExpressRequest /

Width

optional

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

For example: <Width>15.5</Width> 

decimal

minExclusive=0.0
totalDigits=10  

HoldForPickupExpressRequest / 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  

HoldForPickupExpressRequest / 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  

HoldForPickupExpressRequest /

Girth

optional

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

 
For example: <Girth>11</Girth> 

decimal

minExclusive=0.0
totalDigits=10  

HoldForPickupExpressRequest /

NineDigitRoutingZip

optional

Indicates type of IMPB barcode format is desired.  For future use - nine digit routing zip code only option for Hold For Pickup.

boolean

default=true

HoldForPickupExpressRequest /

ExtraServices

optional

Allows selection of extra services other than insurance.

(group)

 

HoldForPickupExpressRequest / ExtraServices / ExtraService

optional, repeating up to unbounded times

Use to specify extra services.  Currently available services are:

 

Service Name

ServiceID

 

Adult Signature

AdultSignature

(Deprecated)

Adult Signature Restricted Delivery

AdultSigRestricted

(Deprecated)

 

Adult Signature

19

Adult Signature Restricted Delivery

20

10:30 AM Delivery

200

 

 

 

For example: <ExtraService>19</ExtraService>

string

enumeration=19

enumeration=20

enumeration=200

 

enumeration= AdultSignature (Deprecated)

enumeration= AdultSigRestricted (Deprecated)

 

HoldForPickupExpressRequest /

ReturnCommitments

optional

Indicates if commitment information should be returned.

 

For example: <ReturnCommitments>True</ReturnCommitments>

boolean

default=false

HoldForPickupExpressRequest / Content

optional

Groups Content elements when a special Content is included in the shipment.

(group)

 

HoldForPickupExpressRequest / Content / ContentType

required

The type of the special content in the shipment.

Required once if Content is included

string

enumeration=HAZMAT

enumeration=Lives

enumeration=CrematedRemains

 

 

HoldForPickupExpressRequest / Content / ContentDescriptor

Optional

Description of contents. Required for ContentType of LIVES

 

For example: <ContentDescriptor>Bees</ContentDescriptor>

string

enumeration=Bees
enumeration=DayOldPoultry

enumeration=AdultBirds

enumeration=Other

HoldForPickupExpressCertifyRequest

required once

API=HoldForPickupExpressCertify This request is used by integrators to test their implementation of the API. The label produced by this API must not enter the mail stream and the tracking number given is not valid and is not manifested. 

(alias)

 


3.1.3     Request Example

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

<HoldForPickupExpressCertifyRequest USERID="XXXX" PASSWORD="PASSWORD0">

    <Option />

    <Revision>2</Revision>

    <EMCAAccount/>

    <EMCAPassword/>

    <ImageParameters/>

    <FromFirstName>Adam</FromFirstName>

    <FromLastName>Smith</FromLastName>

    <FromFirm>ABC Corporation</FromFirm>

<FromAddress1>RM 2100</FromAddress1>

<FromAddress2>475 L’Enfant Plaza SW</FromAddress2>

<FromCity>Washington</FromCity>

<FromState>DC</FromState>

<FromZip5>20260</FromZip5>

<FromZip4/>

    <FromPhone>2125551234</FromPhone>

    <FromContactPreference>EMAIL</FromContactPreference>

    <FromContactMessaging>asmith@email.com</FromContactMessaging>

    <POZipCode />

<ToFirstName>Janice</ToFirstName>

<ToLastName>Dickens</ToLastName>

<ToFirm>XYZ Corporation</ToFirm>

<ToAddress1>Ste 100</ToAddress1>

<ToAddress2>2 Massachusetts Ave NE</ToAddress2>

<ToCity>Washington</ToCity>

<ToState>DC</ToState>

<ToZip5>20212</ToZip5>

    <ToZip4 />

    <ToContactPreference>SMS</ToContactPreference>

    <ToContactMessaging>2125551234@phone.com</ToContactMessaging>

    <FacilityID>1354655</FacilityID>

    <WeightInOunces>260</WeightInOunces>

    <CommercialPrice>false</CommercialPrice>

    <SeparateReceiptPage>false</SeparateReceiptPage>

    <ImageType>PDF</ImageType>

    <LabelDate />

    <CustomerRefNo>XYZ#4105</CustomerRefNo>

    <SenderName>Adam Smith</SenderName>

    <SenderEMail>asmith@email.com</SenderEMail>

    <RecipientName>Janice Dickens</RecipientName>

    <RecipientEMail>jdickens@email.com</RecipientEMail>

    <HoldForManifest>N</HoldForManifest>

    <InsuredAmount>825.50</InsuredAmount>

    <Container>NONRECTANGULAR</Container>

    <Size>LARGE</Size>

    <Width>7</Width>

    <Length>20.5</Length>

    <Height>15</Height>

    <Girth>60</Girth>

 </HoldForPickupExpressCertifyRequest>

3.2       Hold For Pickup Express Response

3.1.1     Response Parameters

Tag Name

Occurs

Description

Type

Validation

HoldForPickupExpressResponse

required once

The XML document returned in response to a HoldForPickupExpressRequest. Alternatively, the Web Tools Error document may be returned if the request could not be completed.  

(group)

 

HoldForPickupExpressResponse / FacilityID

required once

ID of Pickup Facility from request  

string

 

HoldForPickupExpressResponse / FacilityName

required once

Name of Pickup Facility  

string

 

HoldForPickupExpressResponse / FacilityAddress

required once

Pickup Facility Address  

string

 

HoldForPickupExpressResponse / FacilityCity

required once

Pickup Facility City  

string

 

HoldForPickupExpressResponse / FacilityState

required once

Pickup Facility State  

string

 

HoldForPickupExpressResponse / FacilityZIP

required once

Pickup Facility ZIP Code  

string

 

HoldForPickupExpressResponse / FacilityZIP4

required once

Pickup Facility ZIP Code+4  

string

 

HoldForPickupExpressResponse / Has10amCommitment

required once

Indicative of facility's hold-for-pickup availability.  

boolean

 

HoldForPickupExpressResponse / FromContactPreference

required once

Sender's contact method from request.  

string

enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupExpressResponse / FromContactMessaging

required once

Sender's contact information from request.  

string

 

HoldForPickupExpressResponse / ToContactPreference

required once

Recipient's contact method from request.  

string

enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupExpressResponse / ToContactMessaging

required once

Recipient's contact information from request.  

string

 

HoldForPickupExpressResponse / Postage

required once

Amount of Postage Required  

decimal

 

HoldForPickupExpressResponse / EMHFPConfirmationNumber

required once

Priority Mail Express Tracking Number  

string

 

HoldForPickupExpressResponse / EMHFPLabel

optional

Priority Mail Express Label, if requested (where <ImageType> tag not "None") 

base64Binary

 

HoldForPickupExpressResponse / EMHFPReceipt

optional

Separate Priority Mail Express Customer Online Record, if requested using <SeparateReceiptPage> tag 

base64Binary

 

HoldForPickupExpressResponse / RDC

optional repeating up to 1 times

 

string

 

HoldForPickupExpressResponse / Zone

required once

 

string

 

HoldForPickupExpressResponse / InsuranceFee

optional

 

decimal

minExclusive=0.0
maxInclusive=5000  

HoldForPickupExpressResponse / ExtraServices

optional

For future use.

(group)

 

HoldForPickupExpressResponse / Commitment

optional

Returned if <ReturnCommitments> is true in the request.

(group)

 

HoldForPickupExpressResponse / Commitment / CommitmentName

optional

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

String

 

HoldForPickupExpressResponse /  Commitment / ScheduledDeliveryDate

optional

Date in the YYYY-MM-DD format.

date

 

HoldForPickupExpressResponse / LogMessage

optional

A text message for integrators of this API. It may contain additional information about this particular request/response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.  

string

 

HoldForPickupExpressCertifyResponse

required once

The XML document returned in response to a HoldForPickupExpressCertifyRequest. Alternatively, the Web Tools Error document may be returned if the request could not be completed.  

(alias)

 

3.1.2     Response Example

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

<HoldForPickupExpressCertifyResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <FacilityID>1354655</FacilityID>

    <FacilityName>BENNING</FacilityName>

    <FacilityAddress>3937 ˝ MINNESOTA AVE NE</FacilityAddress>

    <FacilityCity>WASHINGTON</FacilityCity>

    <FacilityState>DC</FacilityState>

    <FacilityZIP>20019</FacilityZIP>

    <FacilityZIP4>9997</FacilityZIP4>

    <Has10amCommitment>false</Has10amCommitment>

    <FromContactPreference>EMAIL</FromContactPreference>

    <FromContactMessaging>ASMITH@EMAIL.COM</FromContactMessaging>

    <ToContactPreference>SMS</ToContactPreference>

    <ToContactMessaging>2125551234@PHONE.COM</ToContactMessaging>

    <Postage>48.90</Postage>

    <EMHFPConfirmationNumber>42020019999794718XXXXXXXXXXXXXXXXX</EMHFPConfirmationNumber>

    <EMHFPLabel>ZGVmYXVsdA==</EMHFPLabel>

    <EMHFPReceipt>ZGVmYXVsdA==</EMHFPReceipt>

    <RDC>0007</RDC>

    <Zone>1</Zone>

    <InsuranceFee>3.95</InsuranceFee>

</HoldForPickupExpressCertifyResponse>

 

 

3.1.3     Tagged Label Diagram


4        Hold For Pickup Priority Mail Label API

4.1       Hold For Pickup Priority Request

4.1.1     API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=HoldForPickupPriority

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=HoldForPickupPriorityCertify

&XML=(see below)

 

4.1.2     Request Parameters

Tag Name

Occurs

Description

Type

Validation

HoldForPickupPriorityRequest

required once

API=HoldForPickupPriority (Hold-For-Pickup Priority Mail Label API)
This API can generate a Priority Mail Hold-For-Pickup label with a unique tracking number which is manifested with the customer-contact details provided in the request. When the package arrives at the destination Hold-For-Pickup facility, the customer is notified according to the indicated preference. The individual picking up the package will be required to present identification that agrees with the recipient information provided in the request as well as the last four digits of the tracking number. Facility addresses can be obtained interactively at USPS.com (Locate a Post Office) or programmatically via the HFP Facility Info API. 

(group)

 

HoldForPickupPriorityRequest / @USERID

required

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

NMTOKEN

 

HoldForPickupPriorityRequest / @PASSWORD

optional

For backward compatibility; not validated. 

string

 

HoldForPickupPriorityRequest / Option

required once

For future use.  

empty

 

HoldForPickupPriorityRequest / Revision

optional

In this API use a value of 2 to trigger new functionality.

For example: <Revision>2</Revision>

string

minLength=0
pattern=\d{1}
pattern=  

HoldForPickupPriorityRequest / ImageParameters

required once

For future use.  

empty

 

HoldForPickupPriorityRequest / FromFirstName

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for first and last names combined.


For example: <FromFirstName>MT</FromFirstName> 

string

minLength=0

maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / FromLastName

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for first and last names combined.


For example: <FromLastName>MARTIAN</FromLastName> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / FromFirm

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for firm name.


For example: <FromFirm>USPS</FromFirm> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / FromAddress1

required once

From address line 1. Use this tag for an apartment or suite number.


For example: <FromAddress1>STE 150</FromAddress1>

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / FromAddress2

required once

From address line 2.

For example: <FromAddress2>6600 ROCKLEDGE DR</FromAddress2> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / FromCity

required once

From city.


For example: <FromCity>BETHESDA</FromCity> 

string

minLength=1
maxLength=23
whiteSpace=collapse  

HoldForPickupPriorityRequest / FromState

required once

From state.


For example: <FromState>MD</FromState> 

string

whiteSpace=collapse
pattern=\w{2}  

HoldForPickupPriorityRequest / FromZip5

required once

From ZIP code.


For example: <FromZip5>210817</FromZip5> 

string

whiteSpace=collapse
pattern=\d{5}  

HoldForPickupPriorityRequest / FromZip4

required once

From ZIP+4 extension.


For example: <FromZip4/> 

string

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

HoldForPickupPriorityRequest / FromPhone

required once

From Phone #. 10 digits required (including area code), with no punctuation.


For example: <FromPhone>5745556191</FromPhone> 

string

whiteSpace=collapse
pattern=\d{10}  

HoldForPickupPriorityRequest / FromContactPreference

required once

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


For example:

<FromContactPreference>EMAIL

</FromContactPreference> 

string

default=EMAIL
whiteSpace=collapse
enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupPriorityRequest / FromContactMessaging

required once

This contains the email address or the text messaging address or is blank depending on the FromContactPreference tag. If the EMAIL or SMS enumeration is used in FromContactPreference, this value must be a syntactically-valid e-mail address. If WAIVED is used, this value must be blank.


For example: <FromContactMessaging>user@anydomain.gov

</FromContactMessaging> 

string

maxLength=64
whiteSpace=collapse
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupPriorityRequest / POZipCode

required once

ZIP Code of Post Office or collection box where item is mailed. Specify when different than FromZip5; otherwise, may be left blank.


For example: <POZipCode/> 

string

whiteSpace=collapse
pattern=\d{5}
pattern=\d{0}  

HoldForPickupPriorityRequest / ToFirstName

required once

This information pertains to the recipient of the package, not the pickup destination. Maximum length: 26 characters for both names.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToFirstName>John</ToFirstName>

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / ToLastName

required once

This information pertains to the recipient of the package, not the pickup destination. Maximum length: 26 characters for both names.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToLastName>Smith</ToLastName> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / ToFirm

required once

This information pertains to the recipient of the package, not the pickup destination. Specify name of firm or leave blank.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToFirm>ABC CORPORATION</ToFirm> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / ToAddress1

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient address line 1 contains an apartment or suite number.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToAddress1/> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / ToAddress2

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient address line 2 contains the street address.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToAddress2>1234 MAIN ST</ToAddress2> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupPriorityRequest / ToCity

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient city.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToCity>ANYTOWN</ToCity> 

string

minLength=1
maxLength=23
whiteSpace=collapse  

HoldForPickupPriorityRequest / ToState

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient state.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToState>MN</ToState> 

string

whiteSpace=collapse
pattern=\w{2}  

HoldForPickupPriorityRequest / ToZip5

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient ZIP code.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToZip5>12345</ToZip5> 

string

whiteSpace=collapse
pattern=\d{5}  

HoldForPickupPriorityRequest / ToZip4

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient ZIP+4 extension.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToZip4/> 

string

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

HoldForPickupPriorityRequest / 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

default=EMAIL
whiteSpace=collapse
enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupPriorityRequest / ToContactMessaging

required once

This contains the email address or the text messaging address or is blank depending on the ToContactPreference tag. If the EMAIL or SMS enumeration is used in ToContactPreference, 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
whiteSpace=collapse
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupPriorityRequest / FacilityID

required once

A FacilityID obtained from the Hold-For-Pickup Facility Information API is required. FacilityID specifies the package destination; that is, the USPS facility where the package will be picked up.


For example: <FacilityID>210454648</FacilityID>  

string

 

HoldForPickupPriorityRequest / WeightInOunces

required once

Package weight. Items must weigh 70 pounds or less.


For example: <WeightInOunces>80</WeightInOunces> 

integer

default=0
minInclusive=0
maxInclusive=1170  

HoldForPickupPriorityRequest / CommercialPrice

optional

Indicates if commercial-base price should be returned. For commercial-base price eligibility, please reference the Domestic Mail Manual at http://pe.usps.com/.

 

For example: <CommercialPrice>False

</CommercialPrice>

boolean

default=false 

HoldForPickupPriorityRequest / SeparateReceiptPage

optional

Label and Customer Online Record Printed on two separate pages. Enter "true" if you want the shipping label and online customer record printed on two separate pages or "false" if you want them printed on the same single page.


For example:

<SeparateReceiptPage>true</SeparateReceiptPage>  

boolean

default=false
 

HoldForPickupPriorityRequest / ImageType

required once

Label Image Type.


For example: <ImageType>PDF</ImageType>  

string

whiteSpace=collapse
enumeration=PDF
enumeration=TIF
enumeration=NONE  

HoldForPickupPriorityRequest / 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:

 

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

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

 

For example:

<LabelDate>01/10/2010</LabelDate>

string

whiteSpace=collapse

minLength=0
pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?
pattern=\d{1,2}-\w{3}-\d\d(\d\d)?
pattern=\d{0}  

HoldForPickupPriorityRequest / CustomerRefNo

optional

User-assigned number for caller's use. Appears on label.


For example: <CustomerRefNo>123-ABCD-56789F</CustomerRefNo> 

string

minLength=0
maxLength=30
whiteSpace=collapse  

HoldForPickupPriorityRequest / SenderName

optional

Name of E-mail Sender. If the HoldForPickupPriorityRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. SenderName, if specified, is used to sign the e-mail.


For example: <SenderName/>  

string

minLength=0
whiteSpace=collapse
maxLength=50  

HoldForPickupPriorityRequest / SenderEMail

optional

E-mail Address of Sender. A single valid e-mail address must be used. If the HoldForPickupPriorityRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. If SenderEMail is specified, then the e-mail is cc:'d to this address. It also appears as contact information in the body of the message.


For example: <SenderEMail></SenderEMail>  

string

whiteSpace=collapse
maxLength=100
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupPriorityRequest / RecipientName

optional

Name of E-mail Recipient. If the HoldForPickupPriorityRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. RecipientName, if specified, is used in the message salutation.


For example: <RecipientName/> 

string

minLength=0
whiteSpace=collapse
maxLength=50  

HoldForPickupPriorityRequest / RecipientEMail

optional

E-mail Address of Recipient. A single valid e-mail address must be used. If this tag is specified, an e-mail is created and sent to this recipient address when the label is created. This e-mail contains the tracking number and the scheduled shipment date. This tag is optional but it is the only tag required to activate the e-mail feature; SenderName, SenderEMail, and RecipientName are always optional.


For example: <RecipientEMail></RecipientEMail> 

string

whiteSpace=collapse
maxLength=100
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupPriorityRequest / HoldForManifest

optional

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

string

enumeration=Y
enumeration=N

HoldForPickupPriorityRequest / InsuredAmount

optional

Use this tag for entering an insurance amount, if applicable.

For example: <InsuredAmount>100.00</InsuredAmount> 

decimal

default=0
minInclusive=0
maxInclusive=9999.99
totalDigits=8
whiteSpace=collapse  

HoldForPickupPriorityRequest / Container

optional

Use to specify special containers or container attributes that may affect postage; otherwise, leave blank.  Required when <Revision>=’2’.

 

Note: RECTANGULAR or NONRECTANGULAR must be indicated when <Size>LARGE</Size>.


For example: <Container>RECTANGULAR</Container> 

string

whiteSpace=collapse
enumeration=VARIABLE

enumeration=RECTANGULAR
enumeration=NONRECTANGULAR

enumeration=FLAT RATE ENVELOPE

enumeration=LEGAL FLAT RATE ENVELOPE

enumeration=PADDED FLAT RATE ENVELOPE

enumeration=FLAT RATE BOX

HoldForPickupPriorityRequest /

Size

optional

Required when <Revision>=’2’. Defined as follows:

 

REGULAR: all package dimensions are under 12’’;

LARGE: any package dimension is greater than 12’’

 

For example: <Size>REGULAR</Size> 

string

whiteSpace=collapse
enumeration=LARGE
enumeration=REGULAR

HoldForPickupPriorityRequest /

Width

optional

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

For example: <Width>15.5</Width> 

decimal

minExclusive=0.0
totalDigits=10  

HoldForPickupPriorityRequest / 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  

HoldForPickupPriorityRequest / 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  

HoldForPickupPriorityRequest /

Girth

optional

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

 
For example: <Girth>11</Girth> 

decimal

minExclusive=0.0
totalDigits=10  

HoldForPickupPriorityRequest /

ExtraServices

optional

Allows selection of extra services other than insurance.  For future use.

(group)

 

HoldForPickupPriorityRequest /

ReturnCommitments

optional

Indicates if commitment information should be returned.

 

For example: <ReturnCommitments>True</ReturnCommitments>

boolean

default=false

HoldForPickupPriorityRequest / Content

optional

Groups Content elements when a special Content is included in the shipment.

(group)

 

HoldForPickupPriorityRequest / Content / ContentType

required

The type of the special content in the shipment.

Required once if Content is included

string

enumeration=HAZMAT

enumeration=Lives

 

 

HoldForPickupPriorityRequest / Content / ContentDescriptor

Optional

Description of contents. Required for ContentType of LIVES

 

For example: <ContentDescriptor>Bees</ContentDescriptor>

string

enumeration=Bees
enumeration=DayOldPoultry

enumeration=AdultBirds

enumeration=Other

HoldForPickupPriorityCertifyRequest

required once

API=HoldForPickupPriorityCertify This request is used by integrators to test their implementation of the API. The label produced by this API must not enter the mail stream and the tracking number given is not valid and is not manifested. 

(alias)

 


4.1.3     Request Example

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

<HoldForPickupPriorityCertifyRequest USERID="XXXX" PASSWORD="PASSWORD0">

    <Option />

    <Revision>2</Revision>

    <ImageParameters/>

    <FromFirstName>Adam</FromFirstName>

    <FromLastName>Smith</FromLastName>

    <FromFirm>ABC Corporation</FromFirm>

<FromAddress1>RM 2100</FromAddress1>

<FromAddress2>475 L’Enfant Plaza SW</FromAddress2>

<FromCity>Washington</FromCity>

<FromState>DC</FromState>

<FromZip5>20260</FromZip5>

<FromZip4/>

    <FromPhone>2125551234</FromPhone>

    <FromContactPreference>EMAIL</FromContactPreference>

    <FromContactMessaging>asmith@email.com</FromContactMessaging>

    <POZipCode />

<ToFirstName>Janice</ToFirstName>

<ToLastName>Dickens</ToLastName>

<ToFirm>XYZ Corporation</ToFirm>

<ToAddress1>Ste 100</ToAddress1>

<ToAddress2>2 Massachusetts Ave NE</ToAddress2>

<ToCity>Washington</ToCity>

<ToState>DC</ToState>

<ToZip5>20212</ToZip5>

    <ToZip4 />

    <ToContactPreference>SMS</ToContactPreference>

    <ToContactMessaging>2125551234@phone.com</ToContactMessaging>

    <FacilityID>1354655</FacilityID>

    <WeightInOunces>260</WeightInOunces>

    <CommercialPrice>false</CommercialPrice>

    <SeparateReceiptPage>false</SeparateReceiptPage>

    <ImageType>PDF</ImageType>

    <LabelDate />

    <CustomerRefNo>XYZ#4105</CustomerRefNo>

    <SenderName>Adam Smith</SenderName>

    <SenderEMail>asmith@email.com</SenderEMail>

    <RecipientName>Janice Dickens</RecipientName>

    <RecipientEMail>jdickens@email.com</RecipientEMail>

    <HoldForManifest>N</HoldForManifest>

    <InsuredAmount>825.50</InsuredAmount>

    <Container>NONRECTANGULAR</Container>

    <Size>LARGE</Size>

    <Width>7</Width>

    <Length>20.5</Length>

    <Height>15</Height>

    <Girth>60</Girth>

 </HoldForPickupPriorityCertifyRequest>

4.2       Hold For Pickup Priority Response

4.1.1     Response Parameters

Tag Name

Occurs

Description

Type

Validation

HoldForPickupPriorityResponse

required once

The XML document returned in response to a HoldForPickupPriorityRequest. Alternatively, the Web Tools Error document may be returned if the request could not be completed.  

(group)

 

HoldForPickupPriorityResponse / FacilityID

required once

ID of Pickup Facility from request  

string

 

HoldForPickupPriorityResponse / FacilityName

required once

Name of Pickup Facility  

string

 

HoldForPickupPriorityResponse / FacilityAddress

required once

Pickup Facility Address  

string

 

HoldForPickupPriorityResponse / FacilityCity

required once

Pickup Facility City  

string

 

HoldForPickupPriorityResponse / FacilityState

required once

Pickup Facility State  

string

 

HoldForPickupPriorityResponse / FacilityZIP

required once

Pickup Facility ZIP Code  

string

 

HoldForPickupPriorityResponse / FacilityZIP4

required once

Pickup Facility ZIP Code+4  

string

 

HoldForPickupPriorityResponse / FromContactPreference

required once

Sender's contact method from request.  

string

enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupPriorityResponse / FromContactMessaging

required once

Sender's contact information from request.  

string

 

HoldForPickupPriorityResponse / ToContactPreference

required once

Recipient's contact method from request.  

string

enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupPriorityResponse / ToContactMessaging

required once

Recipient's contact information from request.  

string

 

HoldForPickupPriorityResponse / Postage

required once

Amount of Postage Required  

decimal

 

HoldForPickupPriorityResponse / PMHFPConfirmationNumber

required once

Priority Mail Tracking Number  

string

 

HoldForPickupPriorityResponse / PMHFPLabel

optional

Priority Mail Label, if requested (where <ImageType> tag not "None") 

base64Binary

 

HoldForPickupPriorityResponse / RDC

optional repeating up to 1 times

 

string

 

HoldForPickupPriorityResponse / InsuranceFee

optional

 

decimal

minExclusive=0.0
maxInclusive=5000  

HoldForPickupPriorityResponse / ExtraServices

optional

For future use.

(group)

 

HoldForPickupPriorityResponse / Zone

required once

 

string

 

HoldForPickupPriorityResponse / Commitment

optional

Returned if <ReturnCommitments> is true in the request.

(group)

 

HoldForPickupPriorityResponse / Commitment / CommitmentName

optional

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

String

 

HoldForPickupPriorityResponse /  Commitment / ScheduledDeliveryDate

optional

Date in the YYYY-MM-DD format.

date

 

HoldForPickupPriorityResponse / LogMessage

optional

A text message for integrators of this API. It may contain additional information about this particular request/response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.  

string

 

HoldForPickupPriorityCertifyResponse

required once

The XML document returned in response to a HoldForPickupPriorityCertifyRequest. Alternatively, the Web Tools Error document may be returned if the request could not be completed.  

(alias)

 

4.1.2     Response Example

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

<HoldForPickupPriorityCertifyResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <FacilityID>1354655</FacilityID>

    <FacilityName>BENNING</FacilityName>

    <FacilityAddress>3937 ˝ MINNESOTA AVE NE</FacilityAddress>

    <FacilityCity>WASHINGTON</FacilityCity>

    <FacilityState>DC</FacilityState>

    <FacilityZIP>20019</FacilityZIP>

    <FacilityZIP4>9997</FacilityZIP4>

    <FromContactPreference>EMAIL</FromContactPreference>

    <FromContactMessaging>ASMITH@EMAIL.COM</FromContactMessaging>

    <ToContactPreference>SMS</ToContactPreference>

    <ToContactMessaging>2125551234@PHONE.COM</ToContactMessaging>

    <Postage>48.90</Postage>

    <PMHFPConfirmationNumber>42020019999794718XXXXXXXXXXXXXXXXX</PMHFPConfirmationNumber>

    <PMHFPLabel>ZGVmYXVsdA==</PMHFPLabel>

    <PMHFPReceipt>ZGVmYXVsdA==</PMHFPReceipt>

    <RDC>0007</RDC>

    <InsuranceFee>3.95</InsuranceFee>

    <Zone>1</Zone>

</HoldForPickupPriorityCertifyResponse>

 

 

4.1.3     Sample Label

5        Hold For Pickup First Class Mail Label API

5.1       Hold For Pickup First Class Request

5.1.1     API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=HoldForPickupFirstClass

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=HoldForPickupFirstClassCertify

&XML=(see below)

 


5.1.2     Request Parameters

Tag Name

Occurs

Description

Type

Validation

HoldForPickupFirstClassRequest

required once

API=HoldForPickupFirstClass (Hold-For-Pickup FirstClass Mail Label API)
This API can generate an First Class Mail Hold-For-Pickup label with a unique tracking number which is manifested with the customer-contact details provided in the request. When the package arrives at the destination Hold-For-Pickup facility, the customer is notified according to the indicated preference. The individual picking up the package will be required to present identification that agrees with the recipient information provided in the request as well as the last four digits of the tracking number. Facility addresses can be obtained interactively at USPS.com (Locate a Post Office) or programmatically via the HFP Facility Info API. 

(group)

 

HoldForPickupFirstClassRequest / @USERID

required

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

NMTOKEN

 

HoldForPickupFirstClassRequest / @PASSWORD

optional

For backward compatibility; not validated. 

string

 

HoldForPickupFirstClassRequest / Option

required once

For future use.  

empty

 

HoldForPickupFirstClassRequest / Revision

optional

In this API use a value of 2 to trigger new functionality.

For example: <Revision>2</Revision>

string

minLength=0
pattern=\d{1}
pattern=  

HoldForPickupFirstClassRequest / ImageParameters

required once

For future use.  

empty

 

HoldForPickupFirstClassRequest / FromFirstName

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for first and last names combined.


For example: <FromFirstName>MT</FromFirstName> 

string

minLength=0

maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / FromLastName

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for first and last names combined.


For example: <FromLastName>MARTIAN</FromLastName> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / FromFirm

required once

Values for either First and Last Name of Sender or Firm must be sent. Maximum Length: 26 characters for firm name.


For example: <FromFirm>USPS</FromFirm> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / FromAddress1

required once

From address line 1. Use this tag for an apartment or suite number.


For example: <FromAddress1>STE 150</FromAddress1>

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / FromAddress2

required once

From address line 2.

For example: <FromAddress2>6600 ROCKLEDGE DR</FromAddress2> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / FromCity

required once

From city.


For example: <FromCity>BETHESDA</FromCity> 

string

minLength=1
maxLength=23
whiteSpace=collapse  

HoldForPickupFirstClassRequest / FromState

required once

From state.


For example: <FromState>MD</FromState> 

string

whiteSpace=collapse
pattern=\w{2}  

HoldForPickupFirstClassRequest / FromZip5

required once

From ZIP code.


For example: <FromZip5>210817</FromZip5> 

string

whiteSpace=collapse
pattern=\d{5}  

HoldForPickupFirstClassRequest / FromZip4

required once

From ZIP+4 extension.


For example: <FromZip4/> 

string

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

HoldForPickupFirstClassRequest / FromPhone

required once

From Phone #. 10 digits required (including area code), with no punctuation.


For example: <FromPhone>5745556191</FromPhone> 

string

whiteSpace=collapse
pattern=\d{10}  

HoldForPickupFirstClassRequest / FromContactPreference

required once

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


For example:

<FromContactPreference>EMAIL

</FromContactPreference> 

string

default=EMAIL
whiteSpace=collapse
enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupFirstClassRequest / FromContactMessaging

required once

This contains the email address or the text messaging address or is blank depending on the FromContactPreference tag. If the EMAIL or SMS enumeration is used in FromContactPreference, this value must be a syntactically-valid e-mail address. If WAIVED is used, this value must be blank.


For example: <FromContactMessaging>user@anydomain.gov

</FromContactMessaging> 

string

maxLength=64
whiteSpace=collapse
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupFirstClassRequest / POZipCode

required once

ZIP Code of Post Office or collection box where item is mailed. Specify when different than FromZip5; otherwise, may be left blank.


For example: <POZipCode/> 

string

whiteSpace=collapse
pattern=\d{5}
pattern=\d{0}  

HoldForPickupFirstClassRequest / ToFirstName

required once

This information pertains to the recipient of the package, not the pickup destination. Maximum length: 26 characters for both names.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToFirstName>John</ToFirstName>

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / ToLastName

required once

This information pertains to the recipient of the package, not the pickup destination. Maximum length: 26 characters for both names.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToLastName>Smith</ToLastName> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / ToFirm

required once

This information pertains to the recipient of the package, not the pickup destination. Specify name of firm or leave blank.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToFirm>ABC CORPORATION</ToFirm> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / ToAddress1

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient address line 1 contains an apartment or suite number.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToAddress1/> 

string

minLength=0
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / ToAddress2

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient address line 2 contains the street address.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToAddress2>1234 MAIN ST</ToAddress2> 

string

minLength=1
maxLength=26
whiteSpace=collapse  

HoldForPickupFirstClassRequest / ToCity

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient city.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToCity>ANYTOWN</ToCity> 

string

minLength=1
maxLength=23
whiteSpace=collapse  

HoldForPickupFirstClassRequest / ToState

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient state.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToState>MN</ToState> 

string

whiteSpace=collapse
pattern=\w{2}  

HoldForPickupFirstClassRequest / ToZip5

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient ZIP code.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToZip5>12345</ToZip5> 

string

whiteSpace=collapse
pattern=\d{5}  

HoldForPickupFirstClassRequest / ToZip4

required once

This information pertains to the recipient of the package, not the pickup destination. Recipient ZIP+4 extension.


The "To" address is used to identify the individual picking up the package at the pickup facility.


For example: <ToZip4/> 

string

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

HoldForPickupFirstClassRequest / 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

default=EMAIL
whiteSpace=collapse
enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupFirstClassRequest / ToContactMessaging

required once

This contains the email address or the text messaging address or is blank depending on the ToContactPreference tag. If the EMAIL or SMS enumeration is used in ToContactPreference, 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
whiteSpace=collapse
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupFirstClassRequest / FacilityID

required once

A FacilityID obtained from the Hold-For-Pickup Facility Information API is required. FacilityID specifies the package destination; that is, the USPS facility where the package will be picked up.


For example: <FacilityID>210454648</FacilityID>  

string

 

HoldForPickupFirstClassRequest / WeightInOunces

required once

Package weight. Items must weigh 70 pounds or less.


For example: <WeightInOunces>80</WeightInOunces> 

integer

default=0
minInclusive=0
maxInclusive=1170  

HoldForPickupFirstClassRequest / CommercialPrice

optional

Indicates if commercial-base price should be returned. For commercial-base price eligibility, please reference the Domestic Mail Manual at http://pe.usps.com/.

 

For example: <CommercialPrice>False

</CommercialPrice>

boolean

default=false 

HoldForPickupFirstClassRequest / SeparateReceiptPage

optional

Label and Customer Online Record Printed on two separate pages. Enter "true" if you want the shipping label and online customer record printed on two separate pages or "false" if you want them printed on the same single page.


For example:

<SeparateReceiptPage>true</SeparateReceiptPage>  

boolean

default=false
 

HoldForPickupFirstClassRequest / ImageType

required once

Label Image Type.


For example: <ImageType>PDF</ImageType>  

string

whiteSpace=collapse
enumeration=PDF
enumeration=TIF
enumeration=NONE  

HoldForPickupFirstClassRequest / 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:

 

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

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

 

For example:

<LabelDate>01/10/2010</LabelDate>

string

whiteSpace=collapse

minLength=0
pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?
pattern=\d{1,2}-\w{3}-\d\d(\d\d)?
pattern=\d{0}  

HoldForPickupFirstClassRequest / CustomerRefNo

optional

User-assigned number for caller's use. Appears on label.


For example: <CustomerRefNo>123-ABCD-56789F</CustomerRefNo> 

string

minLength=0
maxLength=30
whiteSpace=collapse  

HoldForPickupFirstClassRequest / SenderName

optional

Name of E-mail Sender. If the HoldForPickupFirstClassRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. SenderName, if specified, is used to sign the e-mail.


For example: <SenderName/>  

string

minLength=0
whiteSpace=collapse
maxLength=50  

HoldForPickupFirstClassRequest / SenderEMail

optional

E-mail Address of Sender. A single valid e-mail address must be used. If the HoldForPickupFirstClassRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. If SenderEMail is specified, then the e-mail is cc:'d to this address. It also appears as contact information in the body of the message.


For example: <SenderEMail></SenderEMail>  

string

whiteSpace=collapse
maxLength=100
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupFirstClassRequest / RecipientName

optional

Name of E-mail Recipient. If the HoldForPickupFirstClassRequest / RecipientEMail tag is specified, an e-mail is created and sent to the recipient when the label is created. This e-mail contains the tracking number and the scheduled shipment date. RecipientName, if specified, is used in the message salutation.


For example: <RecipientName/> 

string

minLength=0
whiteSpace=collapse
maxLength=50  

HoldForPickupFirstClassRequest / RecipientEMail

optional

E-mail Address of Recipient. A single valid e-mail address must be used. If this tag is specified, an e-mail is created and sent to this recipient address when the label is created. This e-mail contains the tracking number and the scheduled shipment date. This tag is optional but it is the only tag required to activate the e-mail feature; SenderName, SenderEMail, and RecipientName are always optional.


For example: <RecipientEMail></RecipientEMail> 

string

whiteSpace=collapse
maxLength=100
pattern=\w{0}
pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}  

HoldForPickupFirstClassRequest / HoldForManifest

optional

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

string

enumeration=Y
enumeration=N

HoldForPickupFirstClassRequest / InsuredAmount

optional

Use this tag for entering an insurance amount, if applicable.

For example: <InsuredAmount>100.00</InsuredAmount> 

decimal

default=0
minInclusive=0
maxInclusive=9999.99
totalDigits=8
whiteSpace=collapse  

HoldForPickupFirstClassRequest / Container

optional

Use to specify special containers or container attributes that may affect postage; otherwise, leave blank.  Required when <Revision>=’2’.

 

Note: RECTANGULAR or NONRECTANGULAR must be indicated when <Size>LARGE</Size>.


For example: <Container>RECTANGULAR</Container> 

string

whiteSpace=collapse
enumeration=VARIABLE

enumeration=RECTANGULAR
enumeration=NONRECTANGULAR

enumeration=FLAT RATE ENVELOPE

enumeration=LEGAL FLAT RATE ENVELOPE

enumeration=PADDED FLAT RATE ENVELOPE

enumeration=FLAT RATE BOX

HoldForPickupFirstClassRequest /

Size

optional

Required when <Revision>=’2’. Defined as follows:

 

REGULAR: all package dimensions are under 12’’;

LARGE: any package dimension is greater than 12’’

 

For example: <Size>REGULAR</Size> 

string

whiteSpace=collapse
enumeration=LARGE
enumeration=REGULAR

HoldForPickupFirstClassRequest /

Width

optional

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

For example: <Width>15.5</Width> 

decimal

minExclusive=0.0
totalDigits=10  

HoldForPickupFirstClassRequest / 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  

HoldForPickupFirstClassRequest / 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  

HoldForPickupFirstClassRequest /

Girth

optional

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

 
For example: <Girth>11</Girth> 

decimal

minExclusive=0.0
totalDigits=10  

HoldForPickupFirstClassRequest /

ExtraServices

optional

Allows selection of extra services other than insurance.  For future use.

(group)

 

HoldForPickupFirstClassRequest / Content

optional

Groups Content elements when a special Content is included in the shipment.

(group)

 

HoldForPickupFirstClassRequest / Content / ContentType

required

The type of the special content in the shipment.

Required once if Content is included

string

enumeration=HAZMAT

enumeration=Lives

 

 

HoldForPickupFirstClassRequest / Content / ContentDescriptor

Optional

Description of contents. Required for ContentType of LIVES

 

For example: <ContentDescriptor>Bees</ContentDescriptor>

string

enumeration=Bees
enumeration=DayOldPoultry

enumeration=AdultBirds

enumeration=Other

HoldForPickupFirstClassCertifyRequest

required once

API=HoldForPickupFirstClassCertify This request is used by integrators to test their implementation of the API. The label produced by this API must not enter the mail stream and the tracking number given is not valid and is not manifested. 

(alias)

 


5.1.3     Request Example

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

<HoldForPickupFirstClassCertifyRequest USERID="XXXX" PASSWORD="PASSWORD0">

    <Option />

    <Revision>2</Revision>

    <ImageParameters/>

    <FromFirstName>Adam</FromFirstName>

    <FromLastName>Smith</FromLastName>

    <FromFirm>ABC Corporation</FromFirm>

<FromAddress1>RM 2100</FromAddress1>

<FromAddress2>475 L’Enfant Plaza SW</FromAddress2>

<FromCity>Washington</FromCity>

<FromState>DC</FromState>

<FromZip5>20260</FromZip5>

<FromZip4/>

    <FromPhone>2125551234</FromPhone>

    <FromContactPreference>EMAIL</FromContactPreference>

    <FromContactMessaging>asmith@email.com</FromContactMessaging>

    <POZipCode />

<ToFirstName>Janice</ToFirstName>

<ToLastName>Dickens</ToLastName>

<ToFirm>XYZ Corporation</ToFirm>

<ToAddress1>Ste 100</ToAddress1>

<ToAddress2>2 Massachusetts Ave NE</ToAddress2>

<ToCity>Washington</ToCity>

<ToState>DC</ToState>

<ToZip5>20212</ToZip5>

    <ToZip4 />

    <ToContactPreference>SMS</ToContactPreference>

    <ToContactMessaging>2125551234@phone.com</ToContactMessaging>

    <FacilityID>1354655</FacilityID>

    <WeightInOunces>260</WeightInOunces>

    <CommercialPrice>false</CommercialPrice>

    <SeparateReceiptPage>false</SeparateReceiptPage>

    <ImageType>PDF</ImageType>

    <LabelDate />

    <CustomerRefNo>XYZ#4105</CustomerRefNo>

    <SenderName>Adam Smith</SenderName>

    <SenderEMail>asmith@email.com</SenderEMail>

    <RecipientName>Janice Dickens</RecipientName>

    <RecipientEMail>jdickens@email.com</RecipientEMail>

    <HoldForManifest>N</HoldForManifest>

    <InsuredAmount>825.50</InsuredAmount>

    <Container>NONRECTANGULAR</Container>

    <Size>LARGE</Size>

    <Width>7</Width>

    <Length>20.5</Length>

    <Height>15</Height>

    <Girth>60</Girth>

 </HoldForPickupFirstClassCertifyRequest>

5.2       Hold For Pickup First Class Response

5.1.1     Response Parameters

Tag Name

Occurs

Description

Type

Validation

HoldForPickupFirstClassResponse

required once

The XML document returned in response to a HoldForPickupFirstClassRequest. Alternatively, the Web Tools Error document may be returned if the request could not be completed.  

(group)

 

HoldForPickupFirstClassResponse / FacilityID

required once

ID of Pickup Facility from request  

string

 

HoldForPickupFirstClassResponse / FacilityName

required once

Name of Pickup Facility  

string

 

HoldForPickupFirstClassResponse / FacilityAddress

required once

Pickup Facility Address  

string

 

HoldForPickupFirstClassResponse / FacilityCity

required once

Pickup Facility City  

string

 

HoldForPickupFirstClassResponse / FacilityState

required once

Pickup Facility State  

string

 

HoldForPickupFirstClassResponse / FacilityZIP

required once

Pickup Facility ZIP Code  

string

 

HoldForPickupFirstClassResponse / FacilityZIP4

required once

Pickup Facility ZIP Code+4  

string

 

HoldForPickupFirstClassResponse / FromContactPreference

required once

Sender's contact method from request.  

string

enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupFirstClassResponse / FromContactMessaging

required once

Sender's contact information from request.  

string

 

HoldForPickupFirstClassResponse / ToContactPreference

required once

Recipient's contact method from request.  

string

enumeration=EMAIL
enumeration=SMS
enumeration=WAIVED  

HoldForPickupFirstClassResponse / ToContactMessaging

required once

Recipient's contact information from request.  

string

 

HoldForPickupFirstClassResponse / Postage

required once

Amount of Postage Required  

decimal

 

HoldForPickupFirstClassResponse / FCMHFPConfirmationNumber

required once

First Class Mail Tracking Number  

string

 

HoldForPickupFirstClassResponse / FCMHFPLabel

optional

First Class Mail Label, if requested (where <ImageType> tag not "None") 

base64Binary

 

HoldForPickupFirstClassResponse / RDC

optional repeating up to 1 times

 

string

 

HoldForPickupFirstClassResponse / ExtraServices

optional

For future use.

(group)

 

HoldForPickupFirstClassResponse / Zone

required once

 

string

 

HoldForPickupFirstClassResponse / LogMessage

optional

A text message for integrators of this API. It may contain additional information about this particular request/response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.  

string

 

HoldForPickupFirstClassCertifyResponse

required once

The XML document returned in response to a HoldForPickupFirstClassCertifyRequest. Alternatively, the Web Tools Error document may be returned if the request could not be completed.  

(alias)

 

5.1.2     Response Example

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

<HoldForPickupFirstClassCertifyResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <FacilityID>1354655</FacilityID>

    <FacilityName>BENNING</FacilityName>

    <FacilityAddress>3937 ˝ MINNESOTA AVE NE</FacilityAddress>

    <FacilityCity>WASHINGTON</FacilityCity>

    <FacilityState>DC</FacilityState>

    <FacilityZIP>20019</FacilityZIP>

    <FacilityZIP4>9997</FacilityZIP4>

    <FromContactPreference>EMAIL</FromContactPreference>

    <FromContactMessaging>ASMITH@EMAIL.COM</FromContactMessaging>

    <ToContactPreference>SMS</ToContactPreference>

    <ToContactMessaging>2125551234@PHONE.COM</ToContactMessaging>

    <Postage>48.90</Postage>

    <FCMHFPConfirmationNumber>42020019999794718XXXXXXXXXXXXXXXXX</FCMHFPConfirmationNumber>

    <FCMHFPLabel>ZGVmYXVsdA==</FCMHFPLabel>

    <RDC>0007</RDC>

    <Zone>1</Zone>

</HoldForPickupFirstClassCertifyResponse>

 

 

5.1.3     Sample Label