1.0 Introduction

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

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:

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

1.1 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. If you need further assistance, please contact the USPS Internet Customer Care Center (ICCC) https://Emailus.usps.com/.

2.0 Hold for Pickup Facility Information API

2.1 Overview

Hold For Pickup service is available at approximately 31,000 USPS locations. 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. 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 service standard associated with the mail class. Hold For Pickup shipments are sent to a designated Hold For Pickup location, such as a Post Office, where the shipment can be picked up within five calendar days. 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.

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

Note: This API offers the ability to lookup Hold For Pickup Facilities, not create Hold For Pickup labels themselves.

2.1.1 API Signature

Scheme	Host	Path	API	XML
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=HFPFacilityInfo	&XML=(see below)

2.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
HFPFacilityInfoRequest	Required	API=HFPFacilityInfo	(Alias)
HFPFacilityInfoRequest / USERID	Required	This attribute specifies your Web Tools user ID. See the Developer's Guide for information on obtaining your USERID. For Example: USERID="XXXXXXX"	NMTOKEN
HFPFacilityInfoRequest / PASSWORD	Optional	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. For Example: PASSWORD="XXXXXXX"	NMTOKEN
HFPFacilityInfoRequest / PickupCity	Required	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=1 maxLength=28 whiteSpace=collapse
HFPFacilityInfoRequest / PickupState	Required	Either City/State or ZIP code must be specified. For example: <PickupState>MA</PickupState>	String	minLength=2 maxLength=2 pattern=\w{2} pattern=
HFPFacilityInfoRequest / PickupZIP	Required	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	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
HFPFacilityInfoRequest	Required		(Alias)

2.2.1 Sample Request

Request: HFPFacilityInfo

</HFPFacilityInfoRequest>

2.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
HFPFacilityInfoResponse	Required		(Alias)
HFPFacilityInfoResponse / PickupCity	Required	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	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	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	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 specific 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	ID of Pickup Facility.	String
HFPFacilityInfoResponse / Facility / FacilityName	Required	Name of Pickup Facility	String
HFPFacilityInfoResponse / Facility / FacilityAddress	Required	Pickup Facility Address	String
HFPFacilityInfoResponse / Facility / FacilityCity	Required	Pickup Facility City	String
HFPFacilityInfoResponse / Facility / FacilityState	Required	Pickup Facility State	String
HFPFacilityInfoResponse / Facility / FacilityZIP	Required	Pickup Facility ZIP Code	String
HFPFacilityInfoResponse / Facility / FacilityZIP4	Required	Pickup Facility ZIP Code+4	String
HFPFacilityInfoResponse / Facility / Has10amCommitment	Required	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. With typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.	String
HFPFacilityInfoResponse	Required		(Alias)

2.3.1 Sample Response

Response: HFPFacilityInfo

<FacilityName>PORT CHARLOTTE BRANCH</FacilityName>

<FacilityAddress>3740 TAMIAMI TRL</FacilityAddress>

<FacilityCity>PORT CHARLOTTE</FacilityCity>

<Has10amCommitment>false</Has10amCommitment>

</Facility>

<FacilityName>PORT CHARLOTTE ANNEX</FacilityName>

<FacilityAddress>18100 PAULSON DR</FacilityAddress>

<FacilityCity>PORT CHARLOTTE</FacilityCity>

<Has10amCommitment>false</Has10amCommitment>

</Facility>

/HFPFacilityInfoResponse>