Package Pickup

  

USPS Web Tools™

Application Programming Interface

User's Guide

Document Version 1.7a (2/11/2013)

 

 

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

  

Trademarks

Express Mail, First-Class Mail, Global Express Mail, GXG, Global Priority Mail, Standard Post, Parcel Select, Priority Mail, Express Mail International, First Class Mail International, Priority Mail International, USPS, and ZIP + 4 are registered trademarks of the U.S. Postal Service.

USPS Tracking/Delivery Confirmation, Global Express Guaranteed, International Parcel Post, Priority Mail Global Guaranteed, Signature Confirmation, USPS Web Tools, and ZIP Code are trademarks of the U.S. Postal Service.

Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.

Adobe Acrobat is a trademark of Adobe Systems Incorporated.

DUNS is a registered trademark of Dun & Bradstreet.

 

ãCopyright 2013 United States Postal Service


 

Table of Contents

1.1      Implementation Overview.. 5

Step 1: Register. 6

Step 2: Test Your XML & Certify Your Interface. 6

Step 3: Go Live with Your Web Tool 9

1.2      User ID Restrictions. 9

1.3      USPS Corporate Branding Guidelines. 10

1.3.1            Preferred Reference. 10

1.3.2            Alternative Reference. 11

1.3.3            Trademark Ownership and Use. 11

1.4      XML Overview.. 12

1.5      Error Responses. 12

1.6      Structure of this Guide. 13

2.1      Delivery Timeline. 17

2.1.1            Pickup Times. 17

2.1.2            Deadline for Changing or Canceling a Request 17

2.2      Aviation Mail Security & Hazardous Materials. 17

2.3      Package Pickup Basic Standards. 18

2.3.1            Availability. 18

2.3.2            Volume. 18

2.3.3            Standards. 18

2.3.4            Service Changes. 18

2.3.5            Postage. 18

2.4      Package Pickup FAQs. 18

3.1      User Interface Messages. 19

3.2      Pop-up Messages. 21

4.1      Package Pickup Availability Web Tool Transaction Procedures. 23

4.2      Run Scripted Test 23

Step 1: Build the XML Request 23

Step 2: Make the Internet Connection & Send the XML Request 24

Step 3: Unpack the XML Response. 25

4.3      Run Live Data. 26

Step 1: Build the XML Request 26

Step 2: Make the Internet Connection & Send the XML Request 29

Step 3: Unpack the XML Response. 29

5.1      Package Pickup Schedule Web Tool Transaction Procedures. 31

5.2      Run Scripted Test 31

Step 1: Build the XML Request 31

Step 2: Make the Internet Connection & Send the XML Request 33

Step 3: Unpack the XML Response. 34

5.3      Run Live Data. 36

Step 1: Build the XML Request 36

Step 2: Make the Internet Connection & Send the XML Request 41

Step 3: Unpack the XML Response. 42

6.1      Package Pickup Cancel Web Tool Transaction Procedures. 44

6.2      Run Scripted Test 44

Step 1: Build the XML Request 44

Step 2: Make the Internet Connection & Send the XML Request 45

Step 3: Unpack the XML Response. 46

6.3      Run Live Data. 47

Step 1: Build the XML Request 47

Step 2: Make the Internet Connection & Send the XML Request 49

Step 3: Unpack the XML Response. 50

7.1      Package Pickup Change Web Tool Transaction Procedures. 52

7.2      Run Scripted Test 52

Step 1: Build the XML Request 52

Step 2: Make the Internet Connection & Send the XML Request 54

Step 3: Unpack the XML Response. 55

7.3      Run Live Data. 57

Step 1: Build the XML Request 57

Step 2: Make the Internet Connection & Send the XML Request 62

Step 3: Unpack the XML Response. 62

8.1      Package Pickup Inquiry Web Tool Transaction Procedures. 65

8.2      Run Scripted Test 65

Step 1: Build the XML Request 65

Step 2: Make the Internet Connection & Send the XML Request 66

Step 3: Unpack the XML Response. 67

8.3      Run Live Data. 69

Step 1: Build the XML Request 69

Step 2: Make the Internet Connection & Send the XML Request 71

Step 3: Unpack the XML Response. 72

 


1.0     Introduction To Web Tools

The USPS Web Tools allow developers of web-based and shrink-wrapped applications access to the on-line services of the United States Postal Service (USPS).  They provide easy access to shipping information and services for your customers.  Your customers can utilize the functions provided by the USPS without ever leaving your web site.  Once the Web Tools are integrated, your server communicates through the USPS Web Tools server over HTTP/s using XML (eXtensible Markup Language). 

Important:  Implementing these Web Tools requires experienced programmers who are familiar with Internet and web site development tools and techniques.

There is a Web Tools User's Guide for each Web Tool listed on the Web Tools documentation website.  These user guides provide examples of the XML transactions to the USPS Web Tools server and guidance for installation.

1.1      Implementation Overview

As shown below, before you go live with any of the Package Pickup Web Tools, you must perform testing.  Following the diagram is a brief description of the steps illustrated.

 

Image of steps to go live with Package Pickup Web Tools.
1. Register Online.  Users only have to register once at https://secure.shippingapis.com/registration/ to download and install Web Tools.
2. Test Your XML and Certify your interface  All Web Tools must be tested using scripts provided in this guide and your interfaces must be certified.
3. Call the ICCC. After successful testing, call the ICCC.
4. The ICCC sets you to "Production." After the ICCC verifies your test results, it grants access to use Live data.
5. Go Live with your Web Tool!

Step 1: Register

To use the USPS Web Tools you must be a registered user.  Completing the registration process provides you with your user ID and test server URL.

Image of a Stop SignIf you have not registered, go to Web Tools website and follow the instructions to register for the Web Tools.

Step 2: Test Your XML & Certify Your Interface

The next step is to test your Web Tools.  As a registered user you have been granted access to the test server.  An important note: The test server is set up to only accept the pre-defined XML transactions and return the pre-defined XML responses provided in this document.  For the testing phase, follow the instructions in the Run Scripted Test sections for each Web Tool.

In addition to developing and testing the transaction procedures between your server and the USPS Web Tools server, there are specific business rules that must be incorporated into your user interface.

These business rules ensure the end-user understands the features and service options of our Package Pickup program.  This section defines those specific features that must be incorporated into your site to explain these features to your end-users.

Prior to obtaining access to the Web Tools production server, you will be required to review and certify compliance with the checklist at the end of this section.  This checklist must be signed and submitted to the Internet Customer Care Center before you will be granted access to the production server.

The following table identifies the functionality that must be incorporated into the user interface you create for your end users.

 

Feature or Option

Description

Functionality Required

What you should know and FAQs

This information is displayed on Package Pickup home page.  Information includes links, requirements, and definitions.

Your interface must allow end users to view and access this information.

Request a Package Pickup

Data input fields for customer address.

Interface must allow customer to complete the address fields.

Edit or Cancel Your Request

Users are able to edit or cancel a request.

Interface must allow customer to edit or cancel a request.

Customer Information

Data input fields for customer name and phone number.

Interface must allow customer to complete the name and phone number fields.

Package location

Users are able to identify physical location of package.

Interface must allow customer to choose package location button.  If alternate location is selected, two conditions must be displayed: that there is a half-mile from mailbox location AND there is a passable road condition.  If both conditions cannot be met and package cannot be left in mailbox then cannot leave package button must be selected and customer will be returned to Package Pickup home page.

 

Package Details

Users are able to select type and quantity of packages for pickup.  Estimated total weight must also be input.

Interface must allow customer to choose package type(s) and quantity.  Estimated total weight is also required.

Additional Packages

Users are able to select additional packages button if any package type is selected.

Interface must allow customer to choose package type(s) and quantity. Estimated total weight is also required.  Useful information about international mail must be displayed.  If international is selected window displays instructing customer that package must be handed to postal employee in person.

Summary page

Summary page provides pickup request summary.

Customer must have option to edit, cancel, or submit request.  Confirmation number is assigned upon submission.

 

 


PACKAGE PICKUP PROGRAM

Application Programming Interface Website Functionality Checklist

 

COMPANY NAME:                                                                                                                          

CONTACT NAME:                                                                                                                           

CONTACT PHONE #:                                                                                                                     

USER ID:                                                                                             

Please verify the following functionality on your website.  Check the preceding boxes to indicate compliance on your site.

    My web site allows users to request a Package Pickup request.  Users are prompted for address including ZIP Code, name, and phone number.

    My web site allows users edit or cancel a Package Pickup request.

    My web site allows users to select Package Location.  When specifying package location other than mailbox, the conditions message (no more than ½ mile from mailbox, passable road) must appear.

    My web site allows users to select type and quantity of packages to be picked up.  My web site also allows users to request Additional Packages if any package type has been selected.

    My web site displays the Package Pickup summary page.  

    My web site allows users to cancel or edit a Package Pickup request.

    My web site displays the What You Should Know information box and allows users to access the available links.  My web site also allows users to access the FAQs. 

    My web site allows the user to print a Package Pickup Confirmation Number.

    My web site displays the message while a user completes the pickup request, "If you are mailing an item that contains anything fragile without proper packaging, or is liquid, perishable, or potentially hazardous, it must be presented to a USPS employee for acceptance."

    My web site complies with the "User Interface Messaging" and "Pop-Up Messages" contained in the Package Pickup User's Guide.

    My web site displays the message "You're Sending Express Mail" clarifying service commitment and guarantee details if Express Mail is indicated as a chosen service.

    My web site displays the message "Safety Concerns" while a user completes the pickup request.

  

Signed                                                                                   Date                             

 

Step 3: Go Live with Your Web Tool

At this point, you have completed all testing and are now ready to send Live data and begin full service.  Follow the instructions provided in the Run Live Data sections for each Web Tool.

1.2      User ID Restrictions

The user ID that you have received is for you or your company to use in accordance with the Terms and Conditions of Use to which you agreed during the registration process.  This user ID is not to be shared with others outside your organization, nor is it to be packaged, distributed, or sold to any other person or entity.  Please refer to the Terms and Conditions of Use Agreement for additional restrictions on the use of your user ID.

Warning: If the U.S. Postal Service discovers use of the same user ID from more than one web site, all users will be subject to immediate loss of access to the USPS server and termination of the licenses granted under the Terms and Conditions of Use.

The documentation and sample code contained in the Web Tools User Guide series may be reused and/or distributed to your customers or affiliates to generate awareness, encourage Web Tool use, or provide ease-of-use.  It is your responsibility to ensure that your customers do not use your user ID for any purpose.  Direct your customers to Web Tools website to register, agree to the Terms and Conditions of Use agreement, and receive their own unique user ID.

Note to Software Distributors: The User ID restrictions discussed above are intended for online retailers that use the USPS Web Tools exclusively within their own web sites.  If you plan to distribute software with the USPS Web Tools embedded, contact the ICCC for guidelines.

For more information regarding the USPS Web Tools user ID policy, or for questions regarding the distribution of documentation, send e-mail to uspstechsupport@esecurecare.net.

1.3      USPS Corporate Branding Guidelines

The U.S. Postal Service requests to be referenced and acknowledged as the source of information for all U.S. Postal Service data that has been acquired through the Internet and/or from other sources.  However, this is not mandatory.  The following guidelines should be followed for those that want to authenticate and/or validate the data displayed from the U.S. Postal Service.

1.3.1            Preferred Reference

Use one of the following when the USPS is the only referenced source:

§         "Information provided by http://www.usps.com/."

or

§         Use the official USPS corporate logo or USPS product-specific logos.

Digital copies of USPS corporate trademarks/logos are available through the U.S. Postal Service, Public Policy and Communications Department, Washington, D.C.  You can request the USPS corporate logo and/or product-specific logos by sending an e-mail to ilogo@email.usps.gov.  Requests will be responded to by e-mail within 10 days.  We will review your web site, and if appropriate, provide the logo for usage in accordance with the guidelines and the license grant contained in the Terms and Conditions of Use for Internet Shipping Application Program Interfaces (Web Tools).  If your web page is not available over the Internet, please provide a screen shot of the page where the logo will reside.

When requesting logo(s) you must provide the following information:

§         Company name.

§         URL and page where logo will reside.

§         Type of business.

§         How and where the logo will be used.

§         Contact name.

§         Telephone number.

§         E-mail address.

§         Desired graphic format, e.g., GIF, TIF, JPEG, etc.

§         Logo desired:

____USPS Corporate Eagle logo

____Priority Mail

____Express Mail

____Other (describe)

1.3.2            Alternative Reference

Use one of the following when the USPS is listed with other shipping carriers or web sites:

§         United States Postal Service.

§         U.S. Postal Service.

§         U.S.P.S. (use period after each initial).

The above alternatives are listed in the order of United States Postal Service preference.

1.3.3            Trademark Ownership and Use

The USPS trademarks listed in the front of this guide and any logos requested from USPS Public Policy and Communications Department should not be altered or abbreviated.

USPS trademarks are trademarks owned solely and exclusively by USPS and may be used only in the form and manner, and with appropriate legends prescribed by USPS.  All advertising and other uses of USPS trademarks must include a legend indicating that USPS trademarks are the property of USPS and that they are being used under license from USPS, together with any other legends or marking that may be required by law.  Nothing contained in this document shall be deemed to convey any title or ownership interest to any user except for the nonexclusive rights granted under the Terms and Conditions of Use for Internet Shipping Application Program Interfaces and this document.

1.4      XML Overview

XML uses a hierarchical (tree) element structure.  Each element consists of a start tag of the form <Name>, and an end tag of the form </Name>, between which can be data and other elements.  <Name/> is shorthand for <Name></Name>, an element with no data.  Attributes such as userid can be included in the start tag.  All data and attribute values in this document are for illustration purposes and are to be replaced by the actual values.  Developers must use the order and case for tag names of the sample code contained in this document.  The tabs and carriage returns in the XML structures are for readability only; there is no need for white space in the actual code.

For more information about XML, browse the following web sites:

§         W3C web site

§         XML.com web site

1.5      Error Responses

Error conditions are handled at the main XML document level.  When parsing 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.

1.6      Structure of this Guide

This document provides guidance and step-by-step instructions for installing the Package Pickup Web Tools and fulfilling various administrative requirements.  There are five separate Web Tools to be implemented:

§         Package Pickup Availability Web Tool.

§         Package Pickup Schedule Web Tool.

§         Package Pickup Cancel Web Tool.

§         Package Pickup Change Web Tool.

§         Package Pickup Inquiry Web Tool.

Each Web Tool is described in its own section.  The steps must be followed in the order presented for each Web Tool.  Refer to the Package Pickup Overview section to understand how the five Web Tools work together.

 


2.0     Package Pickup Overview

Image of United States Postal Service carrier.Package Pickup Web Tools provide convenience to you and your customers.  Your carrier will pick up your packages on the next USPS delivery day (Monday through Saturday, excluding holidays) for free.  Package Pickup is available for sending packages using Express Mail, Priority Mail, international delivery services, or for returned merchandise. 

Customers requiring pickup of their packages by the USPS currently have two pickup options available to them:  Package Pickup and Pickup On Demand.  This Web Tools guide applies to Package Pickup only.  Pickup On Demand is only available through the USPS website.  The information below is presented to illustrate the differences between these two options:

Package Pickup

Pickup On Demand

Free, regardless of the number of packages.

Per pickup fee, regardless of the number of packages.

Your carrier picks up the next USPS delivery day when your mail is delivered.

Packages are picked up in a specified timeframe.

Available with domestic Express Mail and Priority Mail services, international delivery services, or for merchandise returns.

Available for Express Mail, Priority Mail, Global Express Guaranteed, or Standard Post services.

Requests must be received by 2:00 AM CST.

Allow a two-hour timeframe for pickups.

Maximum weight per package is 70 pounds.

Maximum weight per package is 70 pounds.

Postage must be prepaid and attached to package(s).

Apply postage to each package.

Packages must be properly sealed and ready for shipment.

Have your packages ready for pickup at the time and day specified.

Packages requiring insurance services need to be taken to a post office.

 

Full Package Pickup functionality relies on the implementation of five separate Web Tools:

§         Package Pickup Availability Web Tool.

§         Package Pickup Schedule Web Tool.

§         Package Pickup Cancel Web Tool.

§         Package Pickup Change Web Tool.

§         Package Pickup Inquiry Web Tool.

The five Package Pickup Web Tools work together to provide seamless service to you and your customers.  Specifically, the functions of each are as follows:

§         The Package Pickup Availability Web Tool checks the availability for Package Pickup at a specific address and informs the user of the first available date for pickup.  Package Pickup is not available for all addresses.

§         The Package Pickup Schedule Web Tool schedules a Package Pickup and provides the user a confirmation number for the scheduled pickup.  Prior to making a Pickup Schedule call, it is recommended to use the Pickup Availability Web Tool to confirm that service is available.  There must be at least one Express Mail package, Priority Mail package, international package, or returned merchandise package for a valid request.  Refer to the Delivery Timeline section for information regarding when pickups are made based on the time of the request.

§         The Package Pickup Cancel Web Tool cancels a scheduled Package Pickup.  To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Pickup Schedule Web Tool request must be entered.  You must enter address information and the confirmation number.  The confirmation number alone cannot be used to cancel or change a scheduled pickup.  Address information must be identical to what was entered when the pickup was scheduled.  To verify the accuracy of your data, you can use the Pickup Inquiry Web Tool.  Refer to the Delivery Timeline section for information regarding deadlines for canceling pickups.

§         The Package Pickup Change Web Tool allows users to change certain data in their original Pickup Schedule request.  To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Pickup Schedule Web Tool request must be entered.  You must enter address information and the confirmation number.  The confirmation number alone cannot be used to cancel or change a scheduled pickup.  The name and phone number of the sender can be changed, along with the number and types of package services, the weight of the packages, and the location of the pickup.  Address data and the confirmation number cannot be changed and must be identical to the original Schedule request.  To verify the accuracy of your data, you can use the Pickup Inquiry Web Tool.  Refer to the Delivery Timeline section for information regarding deadlines for changing pickups.

§         The Package Pickup Inquiry Web Tool provides the data contained in your original Pickup Schedule request.  To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Schedule request must be entered.  By using the Pickup Inquiry Web Tool, you can obtain the data needed.

 


The diagram below illustrates the relationships between the different Package Pickup Web Tools:

Image of decision process flow for package pickup web tools.
1. Need a pickup? If yes, use the Package Pickup Availability Web Tool to determine service availability for the pickup address.
2. If the result from Package Pickup Availability Web Tool indicates service is not available, please take your package to the post office.
3. If the result from Package Pickup Availability Web Tool indicates service is available, then use the Package Pickup Schedule Web Tool to schedule a pickup.
4. After scheduling your pickup, need to change or cancel?  Use the Package Pickup Inquiry Web Tool to retreive information about your scheduled pickup. 
5. Once Package Pickup Inquiry Web Tool details have been received, either use Package Pickup Change Web Tool or Package Pickup Cancel Web Tool by 2:00 AM CST to modify your scheduled pickup.


2.1      Delivery Timeline

For further information about this graphic, please access the long description in section 2.1.1
The timeline illustrates the period between the request and the actual pickup by your carrier:

2.1.1            Pickup Times

Requests made from 2:00 AM Central Standard Time (CST) on Day 1 to 2:00 AM CST on Day 2 will be picked up during your carrier's regular Day 2 route.  If Day 2 is not a USPS delivery day, it will be picked up on the next regular day.  Sundays and USPS holidays are not USPS delivery days.  For a listing of all USPS holidays, please view the USPS Calendar website.

2.1.2            Deadline for Changing or Canceling a Request

A pickup can be cancelled or changed any time before 2:00 AM CT of the day of the pickup.

2.2      Aviation Mail Security & Hazardous Materials

The Aviation Mail Security and Hazardous Materials Programs represent the U.S. Postal Service’s commitment to provide a safe environment for our customers, employees, and the traveling public.

The U.S. Postal Service has taken a proactive role in the areas of aviation mail security and hazardous materials acceptance, handling, and transport for many years.  Training has been provided to our employees, supervisors, and managers.  Each year these programs are modified to meet increased challenges through improved technology.  Our multi-phased programs are in effect 365 days a year, 24 hours a day.  The particulars of our programs are withheld for security reasons.  However, complying with the following restrictions will assist us in securing a safe mailing environment for all of us:

§         Priority Mail envelopes or packages weighing 13 ounces or over with adhesive postage stamps cannot be deposited at unattended receptacles such as collection boxes and lobby drops.  These mail pieces must be taken to your nearest USPS retail unit or may be given to your carrier if you are a known customer to him/her and have included your return address.  Refer to Domestic Mail Manual, Deposit for Priority Mail.

§         International Mail envelopes or packages weighing 13 ounces or over with adhesive postage stamps or customer applied postage meter strips cannot be deposited at unattended mail receptacles such as collection boxes and lobby drops.  These mail pieces must be taken to your nearest USPS retail unit or may be given to your carrier if you are a known customer and have included your return address along with a completed, signed, and dated PS Form 2976 or 2976-A.  Refer to International Mail Manual.

2.3      Package Pickup Basic Standards

2.3.1            Availability

Package Pickup service is available from designated post offices for Express Mail, Priority Mail, international delivery services or returned merchandise.

2.3.2            Volume

There are no limitations on the number of pieces that may be picked up.  High volume requests may require alternative pickup arrangements.

2.3.3            Standards

Each piece of Express Mail or Priority Mail must meet all applicable eligibility and preparation standards.  Material prepared for Express Mail or Priority Mail shipment must meet the applicable standards in Domestic Mail Manual.  Material prepared for international shipments must meet the applicable standards in International Mail Manual. 

2.3.4            Service Changes

The USPS may suspend or refuse pickup service due to exceptional or unsafe situations (e.g., hazardous weather or road conditions, facility emergencies on customer or USPS property, unforeseen employee or vehicle shortages, or unsafe or inadequate mailer facilities).

2.3.5            Postage

The correct amount of postage must be affixed to each piece.  Exception: Express Mail paid with a corporate account or Priority Mail with a merchandise return service permit label do not need to have postage affixed.

2.4      Package Pickup FAQs

For the most up to date answers, consult the Frequently Asked Questions website. 


3.0     Package Pickup Messages

This section provides specific USPS guidelines, recommendations, and requirements for the user interfaces that gathers and displays pickup information.

3.1      User Interface Messages

The following table identifies language that must be incorporated into the user interface that you create for your end users.  The messages are organized according to the appropriate Web Tool.

 

Web Tool(s)

Language to be incorporated

Pickup Availability

Pickup Schedule

What You Should Know

·         Package Pickup is available for the following services:

o        Express Mail

o        Priority Mail

o        Returned merchandise

o        International

·         Pickup occurs the next USPS delivery day.

·         Requests must be received by 2:00 AM CST.

·         Packages must have correct postage affixed.

·         If stamps are used, a face-to-face transaction with your carrier is required.

·         Packages must be properly sealed and ready for shipment.

·         Maximum weight per package is 70 pounds.

·         Packages requiring Postal insurance services need to be taken to a post office.

Pickup Availability

Pickup Schedule

Pickup Cancel

Pickup Change

Change or Cancel Your Request

 

You may change or cancel a pickup anytime before 2:00 AM CST on the day of pickup.  You'll need your Package Pickup Confirmation Number and address.

Pickup Schedule

Important!

 

Please print this page for your records or keep your Package Pickup Confirmation Number in a safe place.  You will need this number if you wish to change or cancel your Package Pickup.

Pickup Cancel

Pickup Change

Changes or cancellation must be submitted before 2:00 AM CST on the day of pickup to take effect.  Otherwise, your Package Pickup request cannot be changed or cancelled online.

 

If this is the case, please leave notification (at the Package Location you indicated in your Package Pickup request) that provides details of your Package Pickup change or cancellation.

Pickup Change

You successfully submitted changes to your request for a Package Pickup.

Important!

 

Please print this page for your records or keep your Package Pickup Confirmation Number in a safe place.  You will need this number if you wish to change or cancel your Package Pickup.

Pickup Cancel

You successfully cancelled your request for a Package Pickup.

 

We hope that Package Pickup will be useful to you soon.

 

Please print this page for your records.

 


3.2      Pop-up Messages

The following (or similar) messages must appear as a pop-up box or similar function to inform your end users of options, errors, and other messages:

Web Tool(s)

Message

Pickup Schedule

(message appears when user completes Pickup Schedule request)

Next USPS Delivery Day

 

When you request a Package Pickup, you are asking your letter carrier to collect your packages the next USPS delivery day.  USPS delivery days are Monday through Saturday, excluding holidays.  Check the USPS Calendar for a list of USPS holidays.

 

Pickup Availability

Pickup Schedule

Pickup Inquiry

Pickup Cancel

Pickup Change

(error message appears if user does not complete all required fields)

We were unable to process your request.

Please complete the field(s) indicated below.

Pickup Schedule

(message appears if service not available to requested address)

Service Not Available for Your Address

 

We regret that the Package Pickup service is not available for your address.  Please take your packages to your local post office.

Pickup Schedule

(message appears if user clicks button asking question at top)

Why Does My Address Look Different?

We standardize and verify your address to make certain that our carriers know where to go to pick up your package. 

 

For example:

Entered:

ABC Movers

1500 East Main Avenue, Suite 201

Springfield, VA 22162

Standardized:

ABC MOVERS

1500 E MAIN AVE STE 201

SPRINGFIELD, VA 22162-1010

 

Pickup Schedule

(message appears when user completes Pickup Schedule request)

If you are mailing an item that contains anything fragile without proper packaging, or is liquid, perishable, or potentially hazardous, it must be presented to a USPS employee for acceptance.

Pickup Schedule

Pickup Change

(message appears if user enters Express Mail as Service Type)

You're Sending Express Mail

 

Express Mail offers guaranteed overnight delivery to most areas.

The service commitment for Express Mail packages varies based on the time the item is mailed, where it is deposited, and its destination.

Due to the different cutoff times for post offices, Express Mail must be presented to an acceptance employee at a post office if you wish to know the Express Mail service commitment.

Call your local post office for guarantee details in your area.

Pickup Schedule

Pickup Change

(message appears when user completes Pickup Schedule request)

Safety Concerns

 

Letter carriers may use their discretion when picking up packages.  Hazards such as snow, ice, obstructed pathways, and dogs may prevent the carrier from collecting a package.

Pickup Schedule

Pickup Change

(message appears when user completes Pickup Schedule request)

For residents of multi-story buildings, please bring your package(s) to a ground level, secured location for pickup.

Pickup Inquiry

Pickup Cancel

Pickup Change

(error message appears if user does not enter Confirmation Number)

Forgot Your Package Pickup Confirmation Number?

 

Your confirmation number cannot be retrieved online.

If you need to change or cancel your Package Pickup request, please leave notification (at the Package Location you indicated in your Package Pickup request) that provides details of your Package Pickup change or cancellation.

 


4.0     Package Pickup Availability Web Tool

The Package Pickup Availability Web Tool checks the availability for Package Pickup at a specific address and informs the user of the first available date for pickup.  Package Pickup is not available for all addresses.

4.1      Package Pickup Availability Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Package Pickup Availability Web Tools server:

Image describing transactional flow of information to and from Package Pickup Availability Web Server.

1. Inputs from user to server via XML request: Pickup Location Address
2. Server tasks with inputs: Determines Pickup availability, Builds XML response.  
3. Outputs to user from server: Pickup Availability, Day of Week for Pickup, First Available Date for Pickup, Carrier Route.

4.2      Run Scripted Test

Step 1: Build the XML Request

For testing purposes, the only value in the test code in this section that you should change is the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.

Testing URL

To make test calls to the Package Pickup Availability server, access is required to a secure server.  Use the Testing URL provided in the registration e-mail.

Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.


Test Request #1

<CarrierPickupAvailabilityRequest USERID="XXXX">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Date>2006-05-04T18:13:51.0Z</Date>

</CarrierPickupAvailabilityRequest>

 

Test Request #2

<CarrierPickupAvailabilityRequest USERID="XXXX">

<FirmName></FirmName>

<SuiteOrApt></SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City></City>

<State></State>

<ZIP5>77058</ZIP5>

<ZIP4></ZIP4>

<Date>2006-05-04T18:13:51.0Z</Date>

</CarrierPickupAvailabilityRequest>

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupAvailability.  The format of the XML transaction is:

https://servername/ShippingAPITest.dll?API=CarrierPickupAvailability&XML=<CarrierPickupAvailabilityRequest USERID="username">……</CarrierPickupAvailabilityRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

Successful Test Responses

For your test to be successful, the following responses to Valid Test Requests should be returned verbatim.

Response to Test Request #1

<?xml version="1.0"?>

<CarrierPickupAvailabilityResponse>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization/>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupAvailabilityResponse>

 

Response to Test Request #2

<?xml version="1.0"?>

<CarrierPickupAvailabilityResponse>

<FirmName/>

<SuiteOrApt/>

<Address2>1390 Market Street</Address2>

<Urbanization/>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupAvailabilityResponse>

 


Scripted Test Error Responses

If any values were changed in your request, the following default error will occur:

<Error>

<Number>-2147218002</Number>

<Source>SOLServerPickupTest;SOLServerPickupTest.CarrierPickupAvailability_Respond</Source>

<Description>Invalid CarrierPickupAvailabilityRequest test submitted.</Description>
<HelpFile></HelpFile>
<HelpContext></HelpContext>

</Error>

Although the input may be valid, the response will still raise this error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of any other returned errors.

Upon successful completion of the scripted test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step-running Live data.

4.3      Run Live Data

Step 1: Build the XML Request

Live XML Tags

The table below presents the XML input tags for generating Live requests and 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.

 

XML Tag

Required/

Optional

Description & Values Allowed

<CarrierPickupAvailabilityRequest…

Required

Input tag exactly as presented.

…USERID="userid">

Required

Use user ID provided with registration.

e.g., <CarrierPickupAvailabilityRequest UserID="yourID">

 

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<FirmName>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Use this tag for a firm or company name.  FirmName is optional except if needed to uniquely identify an address.  Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

 

For example:

<FirmName>ABC Company</FirmName>

<SuiteOrApt>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Use this tag for an apartment or suite number.  SuiteOrApt is optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

 

For example:

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>

Tag & Value Required

Maximum characters allowed: 50.  Use this tag for a street address.

 

For example:

<Address2>1390 Market Street</Address2>

<Urbanization>

Tag Required/

Value Optional

Maximum number of characters allowed: 28.  Use this tag for an Urbanization (for Puerto Rico only).  ZIP Code prefixes 006 to 009, if area is so designated.

<City>

Tag & Value Required

Maximum characters allowed: 30.  Use this tag for a city.  Either ZIP5 or City and State are required.

 

For example: <City>Houston</City>

<State>

Tag & Value Required

Maximum characters allowed: 2.  Use this tag for a state abbreviation.  Either ZIP5 or City and State are required.

 

For example: <State>TX</State>

<ZIP5>

Tag & Value Required

Use this tag for a 5 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 5.  Either ZIP5 or City and State are required.

 

For example: <ZIP5>77058</ZIP5>

<ZIP4>

Tag Required/

Value Optional

Use this tag for a 4 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 4.

 

For example: <ZIP4>1234</ZIP4>

<DATE>

Tag Required/

Value Optional

Use this tag to request a pickup date/time. XML datetime primitive format..

 

For example: 2006-05-04T18:13:51.0Z

 

 

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:

<FirmName>ABC Company</FirmName>

In this instance, you will replace "ABC Company" with the name of the company sending the package when making your request.

Live URL

To make calls to the Package Pickup Availability server, access is required to a secure server.  To gain access, all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to make Live calls.  The ICCC will send an e-mail that contains the Live URL.


Live XML Request Example

The Live XML request should be in the following form and sequence:

<CarrierPickupAvailabilityRequest UserID="XXXX">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

</CarrierPickupAvailabilityRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupAvailability.  The format of the XML transaction is:

https://servername/ShippingAPI.dll?API=CarrierPickupAvailability&XML=<CarrierPickupAvailabilityRequest USERID="username">……</CarrierPickupAvailabilityRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 


XML Output from Unpacked Response

After unpacking the XML response, you will have the output from your request-an XML response with the following tags:

Output

XML Tag

Type of Response

<CarrierPickupAvailabilityResponse>

Firm name sending request

<FirmName>

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

<SuiteOrApt>

Pickup address

<Address2>

Urbanization

<Urbanization>

Pickup city

<City>

Pickup state

<State>

Pickup ZIP Code

<ZIP5>

Pickup ZIP Code+4

<ZIP4>

Day of week for pickup

<DayOfWeek>

Scheduled date for pickup

<Date>

Carrier Route (can be C for City, H for Highway, R for Rural)

<CarrierRoute>

Live XML Response

The Package Pickup Availability Web Tool returns the following information if pickup is available to the supplied address:

<CarrierPickupAvailabilityResponse>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<DayOfWeek>Monday</DayOfWeek>

<Date>4/01/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupAvailabilityResponse>

 

If an error message is returned, refer to the Error Responses section for an explanation.

 


5.0     Package Pickup Schedule Web Tool

The Package Pickup Schedule Web Tool schedules a Package Pickup and provides the user a confirmation number for the scheduled pickup.  Prior to making a Pickup Schedule call, it is recommended to use the Pickup Availability Web Tool to confirm that service is available.  There must be at least one Express Mail package or one Priority Mail package or on international package or one returned merchandise package for a valid request.  Refer to the Delivery Timeline section for information regarding when pickups are made based on the time of the request.

5.1      Package Pickup Schedule Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Package Pickup Schedule Web Tool server:

Image describing transactional flow of information to and from Package Pickup Schedule Web Server.

1. Inputs from user to server via XML request: Sender Information, Pickup Address, Number of Packages, Service Requested, Weight, Package Location, Special Instructions. 
2. Server tasks with inputs: Schedules a Pickup, Builds XML response.  
3. Outputs to user from server: Sender Information, Pickup Address, Number of Packages, Service Requested, Weight, Package Location, Special Instructions, Date or Day Scheduled for Pickup, Carrier Route.

5.2      Run Scripted Test

Step 1: Build the XML Request

For testing purposes, the only value in the test code in this section that you should change is the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.


Testing URL

To make test calls to the Package Pickup Schedule server, access is required to a secure server.  Use the Testing URL provided in the registration e-mail.

Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.

Test Request #1

<CarrierPickupScheduleRequest USERID="XXXX">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>ExpressMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>International</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>OtherPackages</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Other</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

</CarrierPickupScheduleRequest>

 

Test Request #2

<CarrierPickupScheduleRequest USERID="XXXX">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName></FirmName>

<SuiteOrApt></SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5></ZIP5>

<ZIP4></ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension></Extension>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions></SpecialInstructions>

</CarrierPickupScheduleRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupSchedule.  The format of the XML transaction is:

https://servername/ShippingAPITest.dll?API=CarrierPickupSchedule&XML=<CarrierPickupScheduleRequest USERID="username">…….</CarrierPickupScheduleRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

Successful Test Responses

For your test to be successful, the following responses to Valid Test Requests should be returned verbatim.

Response to Test Request #1

<?xml version="1.0"?>

<CarrierPickupScheduleResponse>

<FirstName>JOHN</FirstName>

<LastName>DOE</LastName>

<FirmName>ABC CORP.</FirmName>

<SuiteOrApt>SUITE 777</SuiteOrApt>

<Address2>1390 MARKET STREET</Address2>

<Urbanization/>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>ExpressMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>International</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>OtherPackages</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Other</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupScheduleResponse>

 

Response to Test Request #2

<?xml version="1.0"?>

<CarrierPickupScheduleResponse>

<FirstName>JOHN</FirstName>

<LastName>DOE</LastName>

<FirmName/>

<SuiteOrApt/>

<Address2>1390 MARKET STREET</Address2>

<Urbanization/>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension></Extension>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions/>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupScheduleResponse>

 

Scripted Test Error Responses

If any values were changed in your request, the following default error will occur:

<Error>

<Number>-2147218002</Number>
<Source>SOLServerPickupTest;SOLServerPickupTest.CarrierPickupSchedule_Respond</Source>
<Description>Invalid CarrierPickupScheduleRequest test submitted.</Description>
<HelpFile></HelpFile>
<HelpContext></HelpContext>

</Error>


Although the input may be valid, the response will still raise this error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of any other returned errors.

Upon successful completion of the scripted test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step-running Live data.

5.3      Run Live Data

Step 1: Build the XML Request

Live XML Tags

The table below presents the XML input tags for generating Live requests and 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.

XML Tag

Required/

Optional

Description & Values Allowed

<CarrierPickupScheduleRequest

Required

Input tag exactly as presented.

…USERID="userid">

Required

Use user ID provided with registration.

e.g.,<CarrierPickupScheduleRequest USERID="yourID">

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<FirstName>

Tag & Value Required

Maximum characters allowed: 50.  Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used.

 

For example:

<FirstName>John</FirstName>

<LastName>

Tag & Value Required

Maximum characters allowed: 50.  Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used.

 

For example:

<LastName>Doe</LastName>

<FirmName>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

 

Use this tag for a firm or company name.  FirmName is optional except if needed to uniquely identify an address.  Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

 

For example: <FirmName>ABC Company</FirmName>

<SuiteOrApt>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Use this tag for an apartment or suite number.  SuiteOrApt  is optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

 

For example:

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>

Tag & Value Required

Maximum characters allowed: 50.  Use this tag for a street address.

 

For example:

<Address2>1390 Market Street</Address2>

<Urbanization>

Tag Required/

Value Optional

Maximum number of characters allowed: 28.  Use this tag for an Urbanization (for Puerto Rico only).  ZIP Code prefixes 006 to 009, if area is so designated.

<City>

Tag & Value Required

Maximum characters allowed: 30.  Use this tag for a city.  Either ZIP5 or City and State are required.

 

For example: <City>Houston</City>

<State>

Tag & Value Required

Maximum characters allowed: 2.  Use this tag for a state abbreviation.  Either ZIP5 or City and State are required.

 

For example: <State>TX</State>

<ZIP5>

Tag & Value Required

Use this tag for a 5 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 5.  Either ZIP5 or City and State are required.

 

For example: <ZIP5>77058</ZIP5>

<ZIP4>

Tag Required/

Value Optional

Use this tag for a 4 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 4.

 

For example: <ZIP4>1234</ZIP4>

<Phone>

Tag & Value Required

Two formats are allowed: (###) 123-4567 or ###-123-4567.  Maximum characters allowed: 14.

 

For example: <Phone>(555) 555-1234</Phone>

or <Phone>555-555-1234</Phone>

<Extension>

Tag Required/

Value Optional

Maximum characters allowed: 4.

 

For example: <Extension>201</Extension>

<Package>

Tag Required/ No Value Allowed

No values entered with this tag.  <ServiceType> and <Count> tags are embedded under this.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.  If the <Count> for a service type is zero, you do not need to encode a <Package> but you must have at least one <Package> with embedded <ServiceType> and <Count> tags.

<ServiceType>

Tag & Value Required

This tag is embedded under the <Package> tag.  Enter one of the following values:

§         ExpressMail

§         PriorityMail

§         Returns

§         International

§         OtherPackages

If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.

 

For example: <ServiceType>ExpressMail</ServiceType>

<Count>

Tag & Value Required

This tag is embedded under the <Package> tag.  Enter the number of packages for the accompanying <ServiceType> tag.  Maximum characters allowed: 3 or 999 packages.  If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.

 

For example: <Count>2</Count>

<EstimatedWeight>

Tag & Value Required

Enter the estimated aggregate weight (in pounds) of all packages being picked up.  Maximum characters allowed: 5.

 

For example: <EstimatedWeight>14</EstimatedWeight>

<PackageLocation>

Tag & Value Required

Enter one of the following values:

§         Front Door

§         Back Door

§         Side Door

§         Knock on Door/Ring Bell

§         Mail Room

§         Office

§         Reception

§         In/At Mailbox

§         Other

Note: "Other" requires information in the value for the <SpecialInstructions> tag.

 

For example:

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>

Tag Required/

Value Optional

Maximum characters allowed: 255. Only alpha, numeric, commas, periods, apostrophes, _, &, -, ( ), ?, #, / +, @ and space characters may be used.

 

For example:

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<EmailAddress>

Tag Optional/

Value Optional

If provided, email notifications will be sent confirming package pickup, or request changes and cancellations. Maximum characters allowed: 50.

 

For example:

<EmailAddress>cpapple@email.com</EmailAddress>

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:

<FirstName>John</FirstName>

In this instance, you will replace "John" with the first name of the person sending the package when making your request.

Live URL

To make calls to the Package Pickup Schedule server, access is required to a secure server.  To gain access all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to make Live calls.  The ICCC will send an e-mail that contains the Live URL.


Live XML Request Example

The Live XML request should be in the following form and sequence:

<CarrierPickupScheduleRequest UserID="XXXX">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

     <ServiceType>ExpressMail</ServiceType>

     <Count>2</Count>

</Package>

<Package>

     <ServiceType>PriorityMail</ServiceType>

     <Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

</CarrierPickupScheduleRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupSchedule.  The format of the XML transaction is:

https://servername/ShippingAPI.dll?API=CarrierPickupSchedule&XML=<CarrierPickupScheduleRequest USERID="username">…….</CarrierPickupScheduleRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

XML Output from Unpacked Response

After unpacking the XML response, you will have the output from your request-an XML response with the following tags:

Output

XML Tag

Type of Response

<CarrierPickupScheduleResponse>

First name of person sending request

<FirstName>

Last name of person sending request

<LastName>

Firm name sending request (if supplied in request)

<FirmName>

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

<SuiteOrApt>

Pickup address

<Address2>

Urbanization (if supplied in request)

<Urbanization>

Pickup city

<City>

Pickup state

<State>

Pickup ZIP Code

<ZIP5>

Pickup ZIP Code+4

<ZIP4>

Phone number of sender

<Phone>

Phone extension of sender (if supplied in request)

<Extension>

Packages to be picked up.  Can be multiple <Packages> with accompanying <ServiceType> and <Count> tags.

<Package>

Types of package services requested

<ServiceType>

Number of packages for each service type requested

<Count>

Total estimated weight of all packages to be picked up

<EstimatedWeight>

Location of pickup

<PackageLocation>

Special instructions for pickup

<SpecialInstructions>

Confirmation number for pickup

<ConfirmationNumber>

Day of week for pickup

<DayOfWeek>

Scheduled date for pickup

<Date>

Carrier Route (can be C for City, H for Highway, R for Rural)

<CarrierRoute>

Email Address (if supplied in request)

<EmailAddress>

 


Live XML Output Example

The Package Pickup Schedule Web Tool returns the following information to the user if the information is valid and pickup is available to the supplied address:

<CarrierPickupScheduleResponse>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

     <ServiceType>ExpressMail</ServiceType>

     <Count>2</Count>

</Package>

<Package>

     <ServiceType>PriorityMail</ServiceType>

     <Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>04/01/2004</Date>

<CarrierRoute>C</CarrierRoute>

</CarrierPickupScheduleResponse>

 

If an error message is returned, refer to the Error Responses section for an explanation.

 


6.0     Package Pickup Cancel Web Tool

The Package Pickup Cancel Web Tool cancels a scheduled Package Pickup.  To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Schedule request must be entered.  You must enter address information and the confirmation number.  Confirmation number alone cannot be used to cancel or change a scheduled pickup.  Address information must be identical to what was entered when the pickup was scheduled.  To ensure the accuracy of your data, you can use the Pickup Inquiry Web Tool.  Refer to the Delivery Timeline section for information regarding deadlines for canceling pickups.

6.1      Package Pickup Cancel Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Package Pickup Cancel Web Tool server:

Image describing transactional flow of information to and from Package Pickup Cancel Web Server.

1. Inputs from user to server via XML request: Pickup Address, Confirmation Number. 
2. Server tasks with inputs: Cancels Pickup Request, Builds XML response.  
3. Outputs to user from server: Pickup Address, Confirmation Number, Status if Cancel Request

6.2      Run Scripted Test

Step 1: Build the XML Request

For testing purposes, the only value in the test code in this section that you should change is the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.

Testing URL

To make test calls to the Package Pickup Cancel server, access is required to a secure server.  Use the Testing URL provided in the registration e-mail.


Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.

Test Request #1

<CarrierPickupCancelRequest USERID="XXXX">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

</CarrierPickupCancelRequest>

 

Test Request #2

<CarrierPickupCancelRequest USERID="XXXX">

<FirmName></FirmName>

<SuiteOrApt></SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City></City>

<State></State>

<ZIP5>77058</ZIP5>

<ZIP4></ZIP4>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

</CarrierPickupCancelRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupCancel.  The format of the XML transaction is:

https://servername/ShippingAPITest.dll?API=CarrierPickupCancel&XML=<CarrierPickupCancelRequest USERID="username">…….</CarrierPickupCancelRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

Successful Test Responses

For your test to be successful, the following responses to Valid Test Requests should be returned verbatim.

Response to Test Request #1

<?xml version="1.0"?>

<CarrierPickupCancelResponse>

<FirmName>ABC CORP.</FirmName>

<SuiteOrApt>SUITE 777</SuiteOrApt>

<Address2>1390 MARKET STREET</Address2>

<Urbanization/>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<Status>Your pickup request was canceled.</Status>

</CarrierPickupCancelResponse>

 

Response to Test Request #2

<?xml version="1.0"?>

<CarrierPickupCancelResponse>

<FirmName/>

<SuiteOrApt/>

<Address2>1390 MARKET STREET</Address2>

<Urbanization/>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<Status>Your pickup request was canceled.</Status>

</CarrierPickupCancelResponse>

 

Scripted Test Error Responses

If any values were changed in your request, the following default error will occur:

<Error>

<Number>-2147218002</Number>
<Source>SOLServerPickupTest;SOLServerPickupTest.CarrierPickupCancel_Respond</Source>
<Description>Invalid CarrierPickupCancelRequest test submitted.</Description>
<HelpFile></HelpFile>
<HelpContext></HelpContext>

</Error>

Although the input may be valid, the response will still raise this error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of any other returned errors.

Upon successful completion of the scripted test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step-running Live data.

6.3      Run Live Data

Step 1: Build the XML Request

Live XML Tags

The table below presents the XML input tags for generating Live requests and 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 cancellation.

XML Tag

Required/

Optional

Description & Values Allowed

<CarrierPickupCancelRequest

Required

Input tag exactly as presented.

…USERID="userid">

Required

Use user ID provided with registration.

e.g.,<CarrierPickupCancelRequest USERID="yourID">

 

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<FirmName>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

 

Use this tag for a firm or company name.  FirmName is optional except if needed to uniquely identify an address.  Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

 

For example: <FirmName>ABC Company</FirmName>

<SuiteOrApt>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Use this tag for an apartment or suite number.  SuiteOrApt  is optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

 

For example: <SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>

Tag & Value Required

Maximum characters allowed: 50.  Use this tag for a street address.

 

For example:

<Address2>1390 Market Street</Address2>

<Urbanization>

Tag Required/

Value Optional

Maximum number of characters allowed: 28.  Use this tag for an Urbanization (for Puerto Rico only).  ZIP Code prefixes 006 to 009, if area is so designated.

<City>

Tag & Value Required

Maximum characters allowed: 30.  Use this tag for a city.  Either ZIP5 or City and State are required

 

For example: <City>Houston</City>

<State>

Tag & Value Required

Maximum characters allowed: 2.  Use this tag for a state abbreviation.  Either ZIP5 or City and State are required.

 

For example: <State>TX</State>

<ZIP5>

Tag & Value Required

Use this tag for a 5 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 5.  Either ZIP5 or City and State are required.

 

For example: <ZIP5>77058</ZIP5>

<ZIP4>

Tag Required/

Value Optional

Use this tag for a 4 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 4.

 

For example: <ZIP4>1234</ZIP4>

<ConfirmationNumber>

Tag & Value Required

Enter exact Confirmation Number returned with Package Pickup Schedule request.

 

For example: <ConfirmationNumber>ABC12345</ConfirmationNumber>

 

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:

<FirmName>ABC Company</FirmName>

In this instance, you will replace "ABC Company" with the name of the company canceling the pickup.

Live URL

To make calls to the Package Pickup Cancel server, access is required to a secure server.  To gain access all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to make Live calls.  The ICCC will send an e-mail that contains the Live URL.

Live XML Request Example

The Live XML request should be in the following form and sequence:

<CarrierPickupCancelRequest UserID="XXXX">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

</CarrierPickupCancelRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupCancel.  The format of the XML transaction is:

https://servername/ShippingAPI.dll?API=CarrierPickupCancel&XML=<CarrierPickupCancelRequest USERID="username">……</CarrierPickupCancelRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

XML Output from Unpacked Response

After unpacking the XML response, you will have the output from your request-an XML response with the following tags:

Output

XML Tag

Type of Response

<CarrierPickupCancelResponse>

Firm name sending request (if supplied in request)

<FirmName>

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

<SuiteOrApt>

Pickup address

<Address2>

Urbanization (if supplied in request)

<Urbanization>

Pickup city

<City>

Pickup state

<State>

Pickup ZIP Code

<ZIP5>

Pickup ZIP Code+4 (if supplied in request)

<ZIP4>

Confirmation number for pickup

<ConfirmationNumber>

Status of request to cancel

<Status>

Live XML Output Example

The Package Pickup Cancel API returns the following information to the user if the information is valid, matches the existing record, and is within the time frames available for cancellation.

<CarrierPickupCancelResponse>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<Status>Your pickup request was cancelled.</Status>

</CarrierPickupCancelRequest>

 

If an error message is returned, refer to the Error Responses section for an explanation.

 


7.0     Package Pickup Change Web Tool

The Package Pickup Change Web Tool allows users to change certain data in their original Pickup Schedule request.  To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Pickup Schedule Web Tool request must be entered.  You must enter address information and the confirmation number.  The confirmation number alone cannot be used to cancel or change a scheduled pickup.  The number and types of package services, the weight of the packages, and the location of the pickup can be changed.  Address data and the confirmation number cannot be changed and must be identical to the original Schedule request.  To verify the accuracy of your data, you can use the Pickup Inquiry Web Tool.  Refer to the Delivery Timeline section for information regarding deadlines for changing pickups.

7.1      Package Pickup Change Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Package Pickup Change Web Tool server:

Image describing transactional flow of information to and from Package Pickup Change Web Server.

1. Inputs from user to server via XML request: Sender Information, Pickup Address, Number of Packages, Service Requested, Weight, Package Location, Special Instructions, Confirmation Number. 
2. Server tasks with inputs: Changes Request Data, Schedules a Pickup, Builds XML response.  
3. Outputs to user from server: Sender Information, Pickup Address, Number of Packages, Service Requested, Weight, Package Location, Special Instructions, Confirmation Number, Date or Day Scheduled for Pickup, Status of Change Request.

7.2      Run Scripted Test

Step 1: Build the XML Request

For testing purposes, the only value in the test code in this section that you should change is the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.

Testing URL

To make test calls to the Package Pickup Change server, access is required to a secure server.  Use the Testing URL provided in the registration e-mail.

Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.

Test Request #1

<CarrierPickupChangeRequest USERID="XXXX">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>ExpressMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>International</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>OtherPackages</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Other</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

</CarrierPickupChangeRequest>

 

Test Request #2

<CarrierPickupChangeRequest USERID="XXXX">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName/>

<SuiteOrApt/>

<Address2>1390 Market Street</Address2>

<Urbanization/>

<City>Houston</City>

<State>TX</State>

<ZIP5/>

<ZIP4/>

<Phone>(555) 555-1234</Phone>

<Extension/>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions/>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

</CarrierPickupChangeRequest>

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupChange.  The format of the XML transaction is:

https://servername/ShippingAPITest.dll?API=CarrierPickupChange&XML=<CarrierPickupChangeRequest USERID="username">……</CarrierPickupChangeRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

Successful Test Responses

For your test to be successful, the following responses to Valid Test Requests should be returned verbatim.

Response to Test Request #1

<?xml version="1.0"?>

<CarrierPickupChangeResponse>

<FirstName>JOHN</FirstName>

<LastName>DOE</LastName>

<FirmName>ABC CORP.</FirmName>

<SuiteOrApt>SUITE 777</SuiteOrApt>

<Address2>1390 MARKET STREET</Address2>

<Urbanization/>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>ExpressMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>International</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>OtherPackages</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Other</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

<Status>Update successful</Status>

</CarrierPickupChangeResponse>

 

Response to Test Request #2

<?xml version="1.0"?>

<CarrierPickupChangeResponse>

<FirstName>JOHN</FirstName>

<LastName>DOE</LastName>

<FirmName/>

<SuiteOrApt/>

<Address2>1390 MARKET STREET</Address2>

<Urbanization/

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension></Extension>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions/>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

<Status>Update successful</Status>

</CarrierPickupChangeResponse>

 

Scripted Test Error Responses

If any values were changed in your request, the following default error will occur:

<Error>

<Number>-2147218002</Number>
<Source>SOLServerPickupTest;SOLServerPickupTest.CarrierPickupChange_Respond</Source>
<Description>Invalid CarrierPickupChangeRequest test submitted.</Description>
<HelpFile></HelpFile>
<HelpContext></HelpContext>

</Error>

Although the input may be valid, the response will still raise this error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of any other returned errors.

Upon successful completion of the scripted test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step-running Live data.

7.3      Run Live Data

Step 1: Build the XML Request

Live XML Tags

The table below presents the XML input tags for generating Live requests and 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 the request to be changed.

XML Tag

Required/

Optional

Description & Values Allowed

<CarrierPickupChangeRequest

Required

Input tag exactly as presented.

…USERID="userid">

Required

Use user ID provided with registration.

e.g.,<CarrierPickupChangeRequest USERID="yourID">

Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<FirstName>

Tag Required

Maximum characters allowed: 50.  Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used.

 

For example: <FirstName>John</FirstName>

<LastName>

Tag Required

Maximum characters allowed: 50.  Only alpha characters, apostrophes, spaces, periods and hyphens "-" may be used.

 

For example: <LastName>Doe</LastName>

<FirmName>

Tag Required/ Value Optional

Maximum characters allowed: 50.  Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

 

Use this tag for a firm or company name.  FirmName is optional except if needed to uniquely identify an address.  Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

 

For example: <FirmName>ABC Company</FirmName>

<SuiteOrApt>

Tag Required/ Value Optional

Maximum characters allowed: 50.  Use this tag for an apartment or suite number.  SuiteOrApt is optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

 

For example: <SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>

Tag & Value Required

Maximum characters allowed: 50.  Use this tag for a street address.

 

For example:

<Address2>1390 Market Street</Address2>

<Urbanization>

Tag Required/ Value Optional

Maximum number of characters allowed: 28.  Use this tag for an Urbanization (for Puerto Rico only).  ZIP Code prefixes 006 to 009, if area is so designated.

<City>

Tag & Value Required

Maximum characters allowed: 30.  Use this tag for a city.  Either ZIP5 or City and State are required.

 

For example: <City>Houston</City>

<State>

Tag & Value Required

Maximum characters allowed: 2.  Use this tag for a state abbreviation.  Either ZIP5 or City and State are required.

 

For example: <State>TX</State>

<ZIP5>

Tag & Value Required

Use this tag for a 5 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 5.  Either ZIP5 or City and State are required.

 

For example: <ZIP5>77058</ZIP5>

<ZIP4>

Tag Required/ Value Optional

Use this tag for a 4 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 4.

 

For example: <ZIP4>1234</ZIP4>

<Phone>

Tag Required/ Value Optional

Two formats are allowed: (###) 123-4567 or ###-123-4567.  Maximum characters allowed: 14.

 

For example: <Phone>(555) 555-1234</Phone>

or <Phone>555-555-1234</Phone>

<Extension>

Tag Required/ Value Optional

Maximum characters allowed: 4.

 

For example: <Extension>201</Extension>

<Package>

Tag Required/

Value may be changed from original request

No values entered with this tag.  <ServiceType> and <Count> tags are embedded under this.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.  If the <Count> for a service type is zero, you do not need to encode a <Package> but you must have at least one <Package> with embedded <ServiceType> and <Count> tags.

<ServiceType>

Tag Required/

Value may be changed from original request

This tag is embedded under the <Package> tag.  Enter one of the following values:

§         ExpressMail

§         PriorityMail

§         Returns

§         International

§         OtherPackages

If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.

 

For example: <ServiceType>ExpressMail</ServiceType>

<Count>

Tag Required/

Value may be changed from original request

This tag is embedded under the <Package> tag.  Enter the number of packages for the accompanying <ServiceType> tag.  Maximum characters allowed: 3 or 999 packages There must be at least one Express Mail Package or one Priority Mail package or one returned merchandise package to make this a valid request.  If your pickup contains more than one Service Type, use additional <Package> tags for each service type with the accompanying <ServiceType> and <Count> tags.  Refer to the Live XML Request Example section, below, to see how these embedded tags are formatted.

 

For example: <Count>2</Count>

<EstimatedWeight>

Tag Required/

Value may be changed from original request

Enter the estimated aggregate weight (in pounds) of all packages being picked up.  Maximum characters allowed: 5.

 

For example: <EstimatedWeight>14</EstimatedWeight>

<PackageLocation>

Tag Required/

Value may be changed from original request

Enter one of the following values:

§         Front Door

§         Back Door

§         Side Door

§         Knock on Door/Ring Bell

§         Mail Room

§         Office

§         Reception

§         In/At Mailbox

§         Other

Note: "Other" requires information in the value for the <SpecialInstructions> tag.

 

For example:

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>

Tag Required/

Value may be changed from original request

Maximum characters allowed: 255. Only alpha, numeric, commas, periods, apostrophes, _, &, -, ( ), ?, #, / +, @ and space characters may be used.

 

For example:

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>

Tag & Value Required

Enter exact Confirmation Number returned with Package Pickup Schedule request.

 

For example: <ConfirmationNumber>ABC12345</ConfirmationNumber>

<EmailAddress>

Tag Optional/

Value Optional

If provided, email notifications will be sent confirming package pickup, or request changes and cancellations. Maximum characters allowed: 50.

 

For example:

<EmailAddress>cpapple@email.com</EmailAddress>

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:

<FirstName>John</FirstName>

In this instance, you will replace "John" with the first name of the person sending the package when making your request.

Live URL

To make calls to the Package Pickup Change server, access is required to a secure server.  To gain access all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to make Live calls.  The ICCC will send an e-mail that contains the Live URL.

Live XML Request Example

The Live XML request should be in the following form and sequence:

<CarrierPickupChangeRequest UserID="XXXX">

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

     <ServiceType>ExpressMail</ServiceType>

     <Count>2</Count>

</Package>

<Package>

     <ServiceType>PriorityMail</ServiceType>

     <Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

</CarrierPickupChangeRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupChange.  The format of the XML transaction is:

https://servername/ShippingAPI.dll?API=CarrierPickupChange&XML=<CarrierPickupChangeRequest USERID="username">…….</CarrierPickupChangeRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

XML Output from Unpacked Response

After unpacking the XML response, you will have the output from your request-an XML response with the following tags:

Output

XML Tag

Type of Response

<CarrierPickupChangeResponse>

First name of person sending request

<FirstName>

Last name of person sending request

<LastName>

Firm name sending request (if supplied in request)

<FirmName>

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

<SuiteOrApt>

Pickup address

<Address2>

Urbanization (if supplied in request)

<Urbanization>

Pickup city

<City>

Pickup state

<State>

Pickup ZIP Code

<ZIP5>

Pickup ZIP Code+4

<ZIP4>

Phone number of sender

<Phone>

Phone extension of sender (if supplied in request)

<Extension>

Packages to be picked up (multiple <Package> tags can be returned with accompanying <ServiceType> and <Count> tags.

<Package>

Types of package services requested

<ServiceType>

Number of packages for each service type requested

<Count>

Total estimated weight of all packages to be picked up

<EstimatedWeight>

Location of pickup

<PackageLocation>

Special instructions for pickup

<SpecialInstructions>

Confirmation number for pickup

<ConfirmationNumber>

Day of week for pickup

<DayOfWeek>

Scheduled date for pickup

<Date>

Status of request to change

<Status>

Email Address (if supplied in request)

<EmailAddress>

Live XML Output Example

The original database record with the information from the request is updated with the changes.  The Package Pickup Change Web Tool returns the following information to the user:

<CarrierPickupChangeResponse>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

     <ServiceType>ExpressMail</ServiceType>

     <Count>2</Count>

</Package>

<Package>

     <ServiceType>PriorityMail</ServiceType>

     <Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions>Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>04/01/2004</Date>

<Status>Update successful</Status>

</CarrierPickupChangeResponse>

 

If an error message is returned, refer to the Error Responses section for an explanation.

 


8.0     Package Pickup Inquiry Web Tool

The Package Pickup Inquiry Web Tool provides the data contained in your original Pickup Schedule request.  To use either the Pickup Cancel or Pickup Change Web Tools, the exact data from the original Schedule request must be entered.  By using the Pickup Inquiry Web Tool, you can obtain the data needed.

8.1      Package Pickup Inquiry Web Tool Transaction Procedures

The illustration below shows the transactional flow of information to and from the USPS Package Pickup Inquiry Web Tool server:

Image describing transactional flow of information to and from Package Pickup Inquiry Web Server.

1. Inputs from user to server via XML request: Sender Information, Pickup Address, Confirmation Number. 
2. Server tasks with inputs: Validates Data, Builds XML response.  
3. Outputs to user from server: Sender Information, Pickup Address, Number of Packages, Service Requested, Weight, Package Location, Special Instructions, Confirmation Number, Date or Day Scheduled for Pickup.

8.2      Run Scripted Test

Step 1: Build the XML Request

For testing purposes, the only value in the test code in this section that you should change is the user ID.  Enter the user ID you received in the registration e-mail for testing.  All remaining code in the test scripts provided below must remain unchanged.

Testing URL

To make test calls to the Package Pickup Inquiry server, access is required to a secure server.  Use the Testing URL provided in the registration e-mail.

Scripted Test Requests

There are two test requests included in this procedure.  All of the test script code contained in this document can be cut and pasted for your use in testing the software.  Be sure to note the request numbers so you can match up the responses you will receive as provided in the Successful Test Responses section.

Test Request #1

<CarrierPickupInquiryRequest USERID="XXXX">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization/>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

</CarrierPickupInquiryRequest>

 

Test Request #2

<CarrierPickupInquiryRequest USERID="XXXX">

<FirmName/>

<SuiteOrApt/>

<Address2>1390 Market Street</Address2>

<Urbanization/>

<City/>

<State/>

<ZIP5>77058</ZIP5>

<ZIP4/>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

</CarrierPickupInquiryRequest>

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupInquiry.  The format of the XML transaction is:

https://servername/ShippingAPITest.dll?API=CarrierPickupInquiry&XML=<CarrierPickupInquiryRequest USERID="username">…….</CarrierPickupInquiryRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

Successful Test Responses

For your test to be successful, the following responses to Valid Test Requests should be returned verbatim.

Response to Test Request #1

<?xml version="1.0"?>

<CarrierPickupInquiryResponse>

<FirstName>JOHN</FirstName>

<LastName>DOE</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>ExpressMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>International</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>OtherPackages</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions></SpecialInstructions>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

</CarrierPickupInquiryResponse>

 

Response to Test Request #2

<?xml version="1.0"?>

<CarrierPickupInquiryResponse>

<FirstName>JOHN</FirstName>

<LastName>DOE</LastName>

<FirmName></FirmName>

<SuiteOrApt></SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>HOUSTON</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

<ServiceType>ExpressMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>PriorityMail</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>International</ServiceType>

<Count>1</Count>

</Package>

<Package>

<ServiceType>OtherPackages</ServiceType>

<Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions></SpecialInstructions>

<ConfirmationNumber>WTC123456789</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>3/1/2004</Date>

</CarrierPickupInquiryResponse>

 

Scripted Test Error Responses

If any values were changed in your request, the following default error will occur:

<Error>

<Number>-2147218002</Number>
<Source>SOLServerPickupTest;SOLServerPickupTest.CarrierPickupInquiry_Respond</Source>
<Description>Invalid CarrierPickupInquiryRequest test submitted.</Description>
<HelpFile></HelpFile>
<HelpContext></HelpContext>

</Error>

Although the input may be valid, the response will still raise this error, because those particular values have not been included in this test server.  Refer to the Error Responses section for an explanation of any other returned errors.

Upon successful completion of the scripted test phase, call the ICCC.  The ICCC will verify your test results and provide you with privileges necessary to proceed to the next step-running Live data.

8.3      Run Live Data

Step 1: Build the XML Request

Live XML Tags

The table below presents the XML input tags for generating Live requests and 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.

XML Tag

Required/

Optional

Description & Values Allowed

<CarrierPickupInquiryRequest…

Required

Input tag exactly as presented.

…USERID="userid">

Required

Use user ID provided with registration.

e.g.,<CarrierPickupInquiryRequest USERID="yourID">


Tags within the above defined call are as follows:

XML Tag

Required/

Optional

Description & Values Allowed

<FirmName>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Only alpha and numeric characters, apostrophes, spaces, hyphens "-" and ampersands "&" may be used.

 

Use this tag for a firm or company name.  FirmName is optional except if needed to uniquely identify an address.  Some firms/companies that have their own ZIP codes require the use of firm name to properly identify their address.

 

For example: <FirmName>ABC Company</FirmName>

<SuiteOrApt>

Tag Required/

Value Optional

Maximum characters allowed: 50.  Use this tag for an apartment or suite number.  SuiteOrApt is optional except if needed to uniquely identify an address at a multiple dwelling address, for example, an apartment building.

 

For example: <SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>

Tag & Value Required

Maximum characters allowed: 50.  Use this tag for a street address.

 

For example:

<Address2>1390 Market Street</Address2>

<Urbanization>

Tag Required/

Value Optional

Maximum number of characters allowed: 28.  Use this tag for an Urbanization (for Puerto Rico only).  ZIP Code prefixes 006 to 009, if area is so designated.

<City>

Tag & Value Required

Maximum characters allowed: 30.  Use this tag for a city.  Either ZIP5 or City and State are required

 

For example: <City>Houston</City>

<State>

Tag & Value Required

Maximum characters allowed: 2.  Use this tag for a state abbreviation.  Either ZIP5 or City and State are required.

 

For example: <State>TX</State>

<ZIP5>

Tag & Value Required

Use this tag for a 5 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 5.  Either ZIP5 or City and State are required.

 

For example: <ZIP5>77058</ZIP5>

<ZIP4>

Tag Required/

Value Optional

Use this tag for a 4 digit ZIP Code.  Input tag exactly as presented--all caps.  Maximum characters allowed: 4.

 

For example: <ZIP4>1234</ZIP4>

<ConfirmationNumber>

Tag & Value Required

Enter exact Confirmation Number returned with Package Pickup Schedule request.

 

For example: <ConfirmationNumber>ABC12345</ConfirmationNumber>

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:

<FirmName>ABC Company</FirmName>

In this instance, you will replace "ABC Company" with the name of the company sending the package when making your request.

Live URL

To make calls to the Package Pickup Inquiry server, access is required to a secure server.  To gain access all users, including those registered for previous Web Tools use, must contact the ICCC for the URL to make Live calls.  The ICCC will send an e-mail that contains the Live URL.

Live XML Request Example

The Live XML request should be in the following form and sequence:

<CarrierPickupInquiryRequest UserID="XXXX">

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

</CarrierPickupInquiryRequest>

 

Step 2: Make the Internet Connection & Send the XML Request

This step involves four separate functions:

1.      Making the connection to the USPS Shipping Web Tools server.

2.      Sending the request (whether Visual Basic, Perl, ASP, or any other language).

3.      Receiving the response from the Web Tools server.

4.      Closing the Internet connection.

The Package Pickup Web Tools require the use of SSL and a secure server.  If you have recently registered, the registration e-mail will have the name of the secure server.  If you are an existing user and do not have the name of the secure server please contact the ICCC.  When sending the XML request, the API name must be specified.  The server name can be found in your Web Tools registration e-mail.  The API name is CarrierPickupInquiry.  The format of the XML transaction is:

https://servername/ShippingAPI.dll?API=CarrierPickupInquiry&XML=<CarrierPickupInquiryRequest USERID="username">…….</CarrierPickupInquiryRequest>

Step 3: Unpack the XML Response

When the USPS Shipping Web Tools returns a response, it will either return a successful response document or an error document. 

XML Output from Unpacked Response

After unpacking the XML response, you will have the output from your request-an XML response with the following tags:

Output

XML Tag

Type of Response

<CarrierPickupInquiryResponse>

First name of person sending request

<FirstName>

Last name of person sending request

<LastName>

Firm name sending request (if supplied in request)

<FirmName>

Suite or apartment (only returned in response if needed to uniquely identify the address, for example, at a multiple dwelling address)

<SuiteOrApt>

Pickup address

<Address2>

Urbanization (if supplied in request)

<Urbanization>

Pickup city

<City>

Pickup state

<State>

Pickup ZIP Code

<ZIP5>

Pickup ZIP Code+4

<ZIP4>

Phone number of sender

<Phone>

Phone extension of sender (if supplied in request)

<Extension>

Packages to be picked up (multiple <Package> tags can be returned with accompanying <ServiceType> and <Count> tags.

<Package>

Types of package services requested

<ServiceType>

Number of packages for each service type requested

<Count>

Total estimated weight of all packages to be picked up

<EstimatedWeight>

Location of pickup

<PackageLocation>

Special instructions for pickup

<SpecialInstructions>

Confirmation number for pickup

<ConfirmationNumber>

Day of week for pickup

<DayOfWeek>

Scheduled date for pickup

<Date>

Email Address

<EmailAddress>

 

 

 


 

Live XML Output Example

The Package Pickup Inquiry Web Tool reads the database record and the following information is returned to the user:

<CarrierPickupInquiryResponse>

<FirstName>John</FirstName>

<LastName>Doe</LastName>

<FirmName>ABC Corp.</FirmName>

<SuiteOrApt>Suite 777</SuiteOrApt>

<Address2>1390 Market Street</Address2>

<Urbanization></Urbanization>

<City>Houston</City>

<State>TX</State>

<ZIP5>77058</ZIP5>

<ZIP4>1234</ZIP4>

<Phone>(555) 555-1234</Phone>

<Extension>201</Extension>

<Package>

     <ServiceType>ExpressMail</ServiceType>

     <Count>2</Count>

</Package>

<Package>

     <ServiceType>PriorityMail</ServiceType>

     <Count>1</Count>

</Package>

<EstimatedWeight>14</EstimatedWeight>

<PackageLocation>Front Door</PackageLocation>

<SpecialInstructions> Packages are behind the screen door.</SpecialInstructions>

<ConfirmationNumber>ABC12345</ConfirmationNumber>

<DayOfWeek>Monday</DayOfWeek>

<Date>04/01/2004</Date>

</CarrierPickupInquiryResponse>

 

If an error message is returned, refer to the Error Responses section for an explanation.