Hold For Pickup Facility Information API  

 

USPS Web Tools™

Application Programming Interface

User Guide

 Version 6.1 (7/13/2023)

 

 

 

 


 

Table of Contents

1.0         Introduction. 3

1.1            Before you get started: 3

2.0         Hold for Pickup Facility Information API 3

2.1            Overview. 3

2.1.1      API Signature. 3

2.2            Request Descriptions. 3

2.2.1      Sample Request 4

2.3            Response Descriptions. 5

2.3.1      Sample Response. 6

 


 

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:

 

<TrackID> EJ123456780US </TrackID>

 

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 USERID="XXXXXXXXX" PASSWORD="">

<PickupCity />

<PickupState/>

<PickupZIP>33952</PickupZIP>

<PickupZIP4 />

<Service />

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

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