Hold For Pickup

Priority Mail Express, Priority Mail and First-Class Mail

 

USPS Web Tools™

Application Programming Interface

User’s Guide

 Document Version 5.0 (01/25/2015)

 

 

United States Postal Service Logo
 

 


 


Table of Contents

Introduction to Web Tools. 3

USPS Hold for Pickup Express API 3

Overview.. 3

1. Hold For Pickup Facility Information API 5

API Signature. 5

Request Descriptions. 5

Sample Request 6

Response Descriptions. 6

Sample Response. 7

2.  Hold For Pickup Express Mail Label API 8

API Signature. 8

Request Descriptions. 9

Sample Request 17

Response Descriptions. 18

Sample Response. 20

Tagged Label Diagram... 20

3.  Hold For Pickup Priority Mail Label API 22

API Signature. 22

Request Descriptions. 22

Sample Request 30

Response Descriptions. 31

Sample Response. 33

Tagged Label Diagram... 34

4.  Hold For Pickup First Class Mail Label API 35

API Signature. 35

Request Descriptions. 35

Sample Request 43

Response Descriptions. 44

Sample Response. 45

Tagged Label Diagram... 46

 

 

 

Introduction to Web Tools

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

 

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

 

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

 

<TrackID> EJ123456780US </TrackID>

 

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

 

Before you get started:

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

Label API access requires extra permissions; contact the Internet Customer Care Center (uspstechnicalsupport@mailps.custhelp.com) to request access. Indicate “Label API Access” in the subject line and explain in the body of the email:

1.       How the shipper intends to purchase and apply postage to the labels

2.       If the label image provided by the API will be modified in any way by the shipper or the software

USPS Hold for Pickup Express API

Overview

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.

Please note that the API labels are printed without postage. Postage must be purchased and applied separately. For more information on postage payment methods, see https://www.usps.com/business/postage-options.htm.


1. Hold For Pickup Facility Information API

API Signature

Scheme

Host

Path

API

XML

http://

production.shippingapis.com

/ShippingAPI.dll

?API=HFPFacilityInfo

&XML=(see below)

Request Descriptions

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

 

Sample Request

Test XML Request:

<HFPFacilityInfoRequest USERID="xxx">

    <PickupCity />

    <PickupState/>

    <PickupZIP>33952</PickupZIP>

    <PickupZIP4 />

    <Service />

</HFPFacilityInfoRequest>

 

Response Descriptions

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

 

 

Sample Response

Test XML Response:

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

 

2.  Hold For Pickup Express Mail Label API

Overview

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.

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)

 

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


 

Request Descriptions

Tag Name

Occurs

Description

Type

Validation

HoldForPickupExpressRequest

required once

API=HoldForPickupExpress (Hold-For-Pickup Express Mail Label API)

(group)

 

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 (Depreciated)

Adult Signature Restricted Delivery

AdultSigRestricted (Depreciated)

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

 

Sample Request

Test XML Request:

https://secure.shippingapis.com/ShippingAPITest.dll?API=HoldForPickupExpress&XML=<HoldForPickupExpressCertifyRequest USERID="XXXX">

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

 

 

Response Descriptions

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

required once

Recipients email address

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

optional

For future use.

(group)

 

HoldForPickupExpressResponse / ExtraServiceName

optional

 

string

 

HoldForPickupExpressResponse / ExtraServiceFee

optional

 

decimal

 

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

 

HoldForPickupExpressCertifyResponse

required once

The XML document returned in response to a HoldForPickupExpressCertifyRequest.

(alias)

 

Sample Response

Test XML Response:

<?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>

 

Tagged Label Diagram

EMHFP DOC label

3.  Hold For Pickup Priority Mail Label API

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)

 

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

 

Request Descriptions

Tag Name

Occurs

Description

Type

Validation

HoldForPickupPriorityRequest

required once

API=HoldForPickupPriority (Hold-For-Pickup Priority Mail Label API)

(group)

 

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

Optional

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_EMAILSMS
enumeration=WAIVED
 

HoldForPickupPriorityRequest / ToContactMessaging

Optional

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

Optional

E-mail address of recipient. Valid e-mail addresses must be used.

Note: No e-mail is returned when  generating a Sample Label request.

 

For example:

<ToContactEMail>John.Smith@abc.com</ToContactEMail>

string

minLength=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 / ExtraService

optional, repeating up to unbounded times

Use to specify extra services.  Currently available services are:

 

Service Name

ServiceID

Insurance

1

Registered Mail

5

Delivery Confirmation

13

Signature Confirmation

15

Adult Signature

19

Adult Signature Restricted Delivery

20

 

For example: <ExtraService>15</ExtraService>

string

enumeration=1

enumeration=5

enumeration=13

enumeration=15

enumeration=19

enumeration=20

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 once – if content included

Use to specify ContentType.  Available types are:

 

ContentType

HAZMAT

CrematedRemains

Lives

Perishable

 

Required if LIVES.

 

Example: < ContentType >Lives</ ContentType >

 

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

string

Enumeration= HAZMAT 

Enumeration= CrematedRemains

Enumeration= Lives

Enumeration= Perishable

HoldForPickupPriorityRequest / Content / ContentDescriptor

optional

Description of content

String

minOccurs="0"

HoldForPickupPriorityCertifyRequest

required once

API=HoldForPickupPriorityCertify

(alias)

 


Sample Request

Test XML Request:

<?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>

 


 

Response Descriptions

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

optional

 

string

 

HoldForPickupPriorityResponse / ExtraServicesName

optional

 

string

 

HoldForPickupPriorityResponse / ExtraServicesFee

optional

 

decimal

 

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

(alias)

 

Sample Response

Test XML Response:

<?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> 

 


 

Tagged Label Diagram

HFPPriority Doc Image

4.  Hold For Pickup First Class Mail Label API

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