USPS Web Tools™

Application Programming Interface

Reference

Document Version 3.3 (02/11/2013)

United States Postal Service Logo

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: uspstechsupport@esecurecare.net

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.

Table of Contents

1 Introduction. 4

2 Signature Confirmation API 4

2.1 Signature Confirmation Request 4

2.1.1 Label Options. 5

2.1.2 API Signature. 7

2.1.3 Request Diagram.. 8

2.1.4 Request Parameters. 13

2.1.5 Request Example. 21

2.2 Signature Confirmation Response. 23

2.2.1 Response Diagram.. 23

2.2.2 Response Parameters. 25

2.2.3 Response Example. 27

1 Introduction

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

For label specifications such as package dimensions, delivery information, etc., please refer to the Domestic Mail Manual (DMM) at http://pe.usps.com/.

2 Signature Confirmation API

2.1 Signature Confirmation Request

With the USPS's Signature Confirmation, you (or your customers) can access information on the Internet about the delivery status of First-Class Mail parcels, Priority Mail and Package Services (Standard Post, Media Mail, and Library Mail), including the date, time, and ZIP Code of delivery, as well as attempted deliveries, forwarding, and returns. Signature Confirmation service is not available to APO/FPO addresses, foreign countries, or most U.S. territories.

The Signature Confirmation Label Web Tool generates a label (and accompanying Customer Online Record), either with or without shipping addresses and information depending on the request. The label returned by the Web Tool is printed by the sender and attached to the package.

Visit Domestic Mail Manual for Signature Confirmation information.

2.1.1 Label Options

You have two label options when requesting Signature Confirmation. The default label option returns the complete label with the Customer Online Record. The following is an example of this option:

Barcode only option Label Graphic from Signature Confirmation response.

“Barcode Only” label option returns a barcode and Package ID Code (PIC) number without the return and delivery name and address. This option is convenient for shippers who already have mailing labels and just want the Signature Confirmation label. Below is an example of this option:

Option 2 Barcode Only Label Graphic from Signature Confirmation response.

2.1.2 API Signature

*Scheme*	*Host*	*Path*	*API*	*XML*
https://	secure.shippingapis.com	/ShippingAPI.dll	?API=SignatureConfirmationV4.0Request	&XML=(see below)
https://	secure.shippingapis.com	/ShippingAPI.dll	?API=SignatureConfirmationCertifyV4Request	&XML=(see below)

2.1.3 Request Diagram

XML schema layout graphic for Signature Confirmation Label Request. Following section describes the XML in more detail. Graphic 1 of 5.

XML schema layout graphic for Signature Confirmation Label Request. Following section describes the XML in more detail. Graphic 2 of 5.

XML schema layout graphic for Signature Confirmation Label Request. Following section describes the XML in more detail. Graphic 3 of 5.

XML schema layout graphic for Signature Confirmation Label Request. Following section describes the XML in more detail. Graphic 4 of 5.

XML schema layout graphic for Signature Confirmation Label Request. Following section describes the XML in more detail. Graphic 5 of 5.

2.1.4 Request Parameters

Tag Name	Occurs	Description	Type	Validation
SignatureConfirmationV4.0Request	required once	Used with API=SignatureConfirmationV4	(group)
SignatureConfirmationV4.0Request / @USERID	required	This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID.	NMTOKEN
SignatureConfirmationV4.0Request / @PASSWORD	optional	For backward compatibility; not validated.	NMTOKEN
SignatureConfirmationV4.0Request / Option	optional	This tag is for future use.	empty
SignatureConfirmationV4.0Request / Revision	optional	This is for versioning of the API's and for triggering response tags for future versions. In this API use a value of 2 to trigger new functionality, namely the new dimensional logic. For example: <Revision>2</Revision>	string	minLength=0 pattern=\d{1} pattern=
SignatureConfirmationV4.0Request / ImageParameters	optional repeating up to 1 times	Enumeration of image parameter to return barcode only or to crop image.	(group)
SignatureConfirmationV4.0Request / ImageParameters / ImageParameter	optional repeating up to 2 times	Returns alternate barcode only label image. For example: <ImageParameter>Barcode Only</ImageParameter>	string	enumeration=BARCODE ONLY enumeration=CROP
SignatureConfirmationV4.0Request / FromName	required once	Values for either First and Last Name of Sender or Firm must be sent. For example: <FromName>John Doe</FromName>	string	minLength=1 maxLength=38
SignatureConfirmationV4.0Request / FromFirm	required once	Firm name; may be left blank. For example: <FromFirm></FromFirm>	string	minLength=0 maxLength=38
SignatureConfirmationV4.0Request / FromAddress1	required once	Use this tag for a suite or apartment number only. Either Address1 or Address2 is required. For example: <FromAddress1/>	string	minLength=0 maxLength=38
SignatureConfirmationV4.0Request / FromAddress2	required once	Use this tag for the primary address line. For example: <FromAddress2>10 Elm Street </FromAddress2>	string	minLength=1 maxLength=38
SignatureConfirmationV4.0Request / FromCity	required once	For example: <FromCity>Anytown</FromCity>	string	minLength=0 maxLength=21
SignatureConfirmationV4.0Request / FromState	required once	Use 2-letter USPS abbreviation. For example: <FromState>ST</FromState>	string	minLength=0 pattern=\w{2} pattern=\w{0}
SignatureConfirmationV4.0Request / FromZip5	required once	Input tag exactly as presented, not all caps. 5 digits required. For example: <FromZip5>01234</FromZip5>	string	pattern=\d{5}
SignatureConfirmationV4.0Request / FromZip4	required once	Input tag exactly as presented, not all caps. If value is entered, 4 digits required. This is the ZIP+4 extension. For example: <FromZip4>5678</FromZip4>	string	minLength=0 pattern=\d{4} pattern=\d{0}
SignatureConfirmationV4.0Request / ToName	required once	Enter a value for the recipient's name. For example: <ToName>Ms. C. P. Apple</ToName>	string	minLength=1 maxLength=38
SignatureConfirmationV4.0Request / ToFirm	required once	Enter a value for the recipient's firm. For example: <ToFirm></ToFirm>	string	minLength=0 maxLength=38
SignatureConfirmationV4.0Request / ToAddress1	required once	Recipient address line 1. Use this tag for an apartment or suite number. For example: <ToAddress1/>	string	minLength=0 maxLength=38
SignatureConfirmationV4.0Request / ToAddress2	required once	Recipient address line 2. Must be a valid address. For example: <ToAddress2>123 Main Ave </ToAddress2>	string	minLength=1 maxLength=38
SignatureConfirmationV4.0Request / ToCity	required once	Recipient city. For example: <ToCity>Anytown</ToCity>	string	minLength=0 maxLength=21
SignatureConfirmationV4.0Request / ToState	required once	Recipient state. Use 2-letter USPS abbreviation. For example: <ToState>ST</ToState>	string	minLength=0 pattern=\w{2} pattern=\w{0}
SignatureConfirmationV4.0Request / ToZip5	required once	Recipient ZIP code. For example: <ToZip5>01234</ToZip5>	string	minLength=0 pattern=\d{5} pattern=
SignatureConfirmationV4.0Request / ToZip4	required once	Recipient ZIP+4 extension. For example: <ToZip5>01234</ToZip5>	string	minLength=0 pattern=\d{4} pattern=\d{0}
SignatureConfirmationV4.0Request / WeightInOunces	required once	Required for postage calculation and manifest record. For example: <WeightInOunces>25 </WeightInOunces>	integer	maxInclusive=1120 minExclusive=0
SignatureConfirmationV4.0Request / ServiceType	required once	Mail service type desired. For example: <ServiceType>Priority</ServiceType>	string	enumeration=Priority enumeration=First Class enumeration=Standard Post enumeration=Media Mail enumeration=Library Mail
SignatureConfirmationV4.0Request / InsuredAmount	optional	Use this tag for entering an insurance amount, if applicable. For example: <InsuredAmount>100.00 </InsuredAmount>	decimal	default=0 minInclusive=0 maxInclusive=9999.99 totalDigits=8 whiteSpace=collapse
SignatureConfirmationV4.0Request / WaiverOfSignature	optional	No Signature Required for Delivery. Enter "true" if you do not want a signature for receipt of the package or "false" if you do. For example: <WaiverOfSignature/>	boolean	default=false
SignatureConfirmationV4.0Request / SeparateReceiptPage	optional	Label & Customer Online Record Printed on two separate pages. Enter "true" if you want the shipping label and online customer record printed on two separate pages or "false" if you want them printed on the same single page. For example: <SeparateReceiptPage/>	boolean	default=false
SignatureConfirmationV4.0Request / POZipCode	optional	ZIP Code of Post Office or collection box where item is mailed. May be different than From ZIP Code. For example: <POZipCode>20770</POZipCode>	string	minLength=0 pattern=\d{5} pattern=
SignatureConfirmationV4.0Request / ImageType	required once	Label Image Type. For example: <ImageType>GIF</ImageType>	string	enumeration=PDF enumeration=GIF enumeration=None
SignatureConfirmationV4.0Request / LabelDate	optional	Date package will be mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in either format: dd-mmm-yyyy, such as 10-Jan-2010, or mm/dd/yyyy, such as 10/25/2010. For example: <LabelDate>10/01/2010</LabelDate>	string	minLength=0 pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?
SignatureConfirmationV4.0Request / CustomerRefNo	optional	User-assigned Number for Internal Use. For example: <CustomerRefNo>123456 </CustomerRefNo>	string	minLength=0 maxLength=30
SignatureConfirmationV4.0Request / AddressServiceRequested	optional	You can request the USPS to alert you when a customer changes their address. This feature is especially useful to ensure correct billing. The words “Address Service Requested” will appear on the shipping label immediately below the return address. This service is not available with the barcode only label option. By using this tag, you will receive the following service with Priority Mail: For 12 months after an address change, the mailpiece is forwarded at no charge. However, a separate notice of the new address is returned to you and an address correction fee is charged. For months 13-18 after an address change, the mailpiece is returned with the new address attached at no charge. After 18 months, or if undeliverable, the mailpiece is returned with the reason for nondelivery attached at no charge. Enter “True” or “False.” False is assumed if no value is entered. For fees for this service with Package Services, refer to the Domestic Mail Manual. For example: <AddressServiceRequested>true </AddressServiceRequested>	boolean	default=false
SignatureConfirmationV4.0Request / SenderName	optional	The name of the person or company sending the email. Note: No e-mail is returned when generating a Sample Label request. For example: <SenderName>John Smith</SenderName>	string	minLength=0
SignatureConfirmationV4.0Request / SenderEMail	optional	E-mail address of sender. Valid e-mail addresses must be used. Note: No e-mail is returned when generating a Sample Label request. For example: <SenderEMail>John.Smith@abc.com </SenderEMail>	string	minLength=0 pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4} pattern=
SignatureConfirmationV4.0Request / RecipientName	optional	The name of the person or company receiving the email. Note: No e-mail is returned when generating a Sample Label request. For example: <RecipientName>Mary Jones</RecipientName>	string	minLength=0 pattern=
SignatureConfirmationV4.0Request / RecipientEMail	optional	E-mail address of recipient. Valid e-mail addresses must be used. Note: No e-mail is returned when generating a Sample Label request. For example: <RecipientEMail>MaryJ@xyz.org </RecipientEMail>	string	minLength=0 pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4} pattern=
SignatureConfirmationV4.0Request / AllowNonCleansedDestAddr	optional	Value of 'true' bypasses destination address cleansing. Non-cleansed destination addresses may result in undeliverable packages.	boolean	default=false
SignatureConfirmationV4.0Request / HoldForManifest	optional	Restricted use. Holds manifest record for possible inclusion in SCAN request.	string	enumeration=Y enumeration=N
SignatureConfirmationV4.0Request / Container	optional	Use to specify special containers or container attributes that may affect postage; otherwise, leave blank. Specifically this is used to indicate various flat and regional rate options for Priority Mail, otherwise the API will assume "simple". Needed to assign an appropriate RDC and to ensure the proper 3 digit service type code is included in the barcode. For example: <Container>VARIABLE</Container>	string	default=VARIABLE whiteSpace=collapse enumeration=VARIABLE enumeration=FLAT RATE ENVELOPE enumeration=LEGAL FLAT RATE ENVELOPE enumeration=PADDED FLAT RATE ENVELOPE enumeration=GIFT CARD FLAT RATE ENVELOPE enumeration=SM FLAT RATE ENVELOPE enumeration=WINDOW FLAT RATE ENVELOPE enumeration=FLAT RATE BOX enumeration=SM FLAT RATE BOX enumeration=MD FLAT RATE BOX enumeration=LG FLAT RATE BOX enumeration=REGIONALRATEBOXA enumeration=REGIONALRATEBOXB enumeration=REGIONALRATEBOXC enumeration=RECTANGULAR enumeration=NONRECTANGULAR
SignatureConfirmationV4.0Request / Size	optional	Defined as follows: REGULAR: all package dimensions are under 12’’; LARGE: any package dimension is greater than 12’’ For example: <Size>REGULAR</Size>	string	whiteSpace=collapse enumeration=REGULAR enumeration=LARGE
SignatureConfirmationV4.0Request / Width	optional	Value must be numeric. Units are inches. Required when Size is LARGE. For example: <Width>5.5</Width>	decimal	minExclusive=0.0 totalDigits=10
SignatureConfirmationV4.0Request / Length	optional	Value must be numeric. Units are inches. Required when Size is LARGE. For example: <Length>11</Length>	decimal	minExclusive=0.0 totalDigits=10
SignatureConfirmationV4.0Request / Height	optional	Value must be numeric. Units are inches. Required when Size is LARGE. For example: <Height>11</Height>	decimal	minExclusive=0.0 totalDigits=10
SignatureConfirmationV4.0Request / Girth	optional	Value must be numeric. Units are inches. Girth is only required when Container = ‘NONRECTANGULAR’ or ‘VARIABLE’ and Size=’LARGE’ . For example: <Girth>11</Girth>	decimal	minExclusive=0.0 totalDigits=10
SignatureConfirmationV4.0Request / Machinable	optional	Machinable is required when: ServiceType = ‘ParcelPost’ For example: <Machinable>true</Machinable>	boolean	default=true whiteSpace=collapse
SignatureConfirmationV4.0Request / CommercialPrice	optional	Indicates if commercial price should be returned. For example: <CommercialPrice>False </CommercialPrice>	boolean	default=false
SignatureConfirmationV4.0Request / ExtraServices	optional	For future use.	(group)
SigConfirmCertifyV4.0Request	required once		(alias)

2.1.5 Request Example

<?xml version="1.0" encoding="UTF-8" ?>

<SigConfirmCertifyV4.0Request USERID="XXXXXX" PASSWORD="XXXXXX">

<FromAddress2>475 L’Enfant Plaza SW</FromAddress2>

<FromCity>Washington</FromCity>

<ToName>Janice Dickens</ToName>

<ToFirm>XYZ Corporation</ToFirm>

<ToAddress2>2 Massachusetts Ave NE</ToAddress2>

<ToCity>Washington</ToCity>

<ServiceType>Priority</ServiceType>

<SeparateReceiptPage>False</SeparateReceiptPage>

<AddressServiceRequested>False</AddressServiceRequested>

<Container>NONRECTANGULAR</Container>

<Size>LARGE</Size>

</SigConfirmCertifyV4.0Request>

Tag Name	Occurs	Description	Type
SignatureConfirmationV4.0Response	required once		(group)
SignatureConfirmationV4.0Response / SignatureConfirmationNumber	required once	Signature Confirmation tracking number	string
SignatureConfirmationV4.0Response / SignatureConfirmationLabel	required once	Signature Confirmation Label, if requested (where <ImageType> tag not "None")	base64Binary
SignatureConfirmationV4.0Response / SignatureConfirmationReceipt	required once	Separate Signature Confirmation Customer Online Record, if requested using <SeparateReceiptPage> tag	base64Binary
SignatureConfirmationV4.0Response / ToName	required once	Name of Recipient	string
SignatureConfirmationV4.0Response / ToFirm	required once	Company Name	string
SignatureConfirmationV4.0Response / ToAddress1	required once	To Address Line 1	string
SignatureConfirmationV4.0Response / ToAddress2	required once	To Address Line 2	string
SignatureConfirmationV4.0Response / ToCity	required once	To City	string
SignatureConfirmationV4.0Response / ToState	required once	To State	string
SignatureConfirmationV4.0Response / ToZip5	required once	To ZIP Code	string
SignatureConfirmationV4.0Response / ToZip4	required once	To ZIP Code+4	string
SignatureConfirmationV4.0Response / Postnet	required once		string
SignatureConfirmationV4.0Response / RDC	optional repeating up to 1 times		string
SignatureConfirmationV4.0Response / Postage	optional	Amount of Postage Required	decimal
SignatureConfirmationV4.0Response / Zone	optional	Postal Zone. Indicates the number of postal rate zones between the origin and destination ZIP codes.	string
SignatureConfirmationV4.0Response / DimensionalWeight	optional		string
SignatureConfirmationV4.0Response / InsuranceFee	optional		string
SignatureConfirmationV4.0Response / ExtraServices	optional	For future use.	(group)
SignatureConfirmationV4.0Response / CarrierRoute	optional		string
SignatureConfirmationV4.0Response / LogMessage	optional repeating up to 1 times	A text message for integrators of this API. It may contain additional information about this particular request/response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.	string
SigConfirmCertifyV4.0Response	required once		(alias)

2.2.3 Response Example

<?xml version="1.0" encoding="UTF-8" ?>

<SigConfirmCertifyV4.0Response>

<SignatureConfirmationNumber>4202077094108XXXXXXXXXXXXXXXXX</SignatureConfirmationNumber>

SUkqAAgAAAASAP4ABAABAAAAAAAAAAA...

</SignatureConfirmationLabel>

<ToName>JANICE DICKENS</ToName>

<ToFirm>XYZ CORPORATION</ToFirm>

<ToAddress2>2 MASSACHUSETTS AVE NE</ToAddress2>

<ToCity>WASHINGTON</ToCity>

</SigConfirmCertifyV4.0Response>