Hold For Pickup Facility Information API  

 

USPS Web Tools™

Application Programming Interface

User’s Guide

 Document Version 5.7 (1/25/2018)

 

 

United States Postal Service Logo
 

 


 


Table of Contents

Introduction to Web Tools. 3

USPS Hold for Pickup Facility Information 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

 

 


 

Introduction to Web Tools

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

Contact the Internet Customer Care Center (uspstechnicalsupport@mailps.custhelp.com) to request access.

USPS Hold for Pickup Facility Information 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.

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.

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

Please note that this API offers the ability to lookup Hold For Pickup Facilities, not create Hold For Pickup labels themselves.

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.

(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=1
maxLength=28
whiteSpace=collapse  

HFPFacilityInfoRequest / PickupState

required once

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

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>