Signature
Confirmation
Label

 

USPS Web Tools™

Application Programming Interface

Reference

Document Version 4.0 (02/06/2014)

 

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 Web Tools API documentation.

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.

Registered Trademarks

Priority Mail, Priority Mail Flat Rate, Priority Mail International, Priority Mail Regional Rate, Global Express Mail, Global Express Guaranteed, Global Priority Mail, Parcel Post, Parcel Select, First-Class Mail, USPS, USPS Web Tools, and ZIP + 4 are registered trademarks of the U.S. Postal Service.

Priority Mail Express, Priority Mail Express 1-Day, Priority Mail Express 2-Day, Priority Mail Express 3-Day, Priority Mail Express DPO, Priority Mail Express International, Priority Mail Express Intl, Priority Mail Express Military, Priority Mail Express Offshore, Priority Mail 1-Day, Priority Mail 2-Day, Priority Mail 3-Day, Priority Mail DPO, Priority Mail Intl, Priority Mail Military, Priority Mail Offshore, Signature Confirmation, Standard Post, USPS Tracking, ZIP, and ZIP Code are trademarks of the U.S. Postal Service.

Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.

Adobe Acrobat and Adobe Reader are trademarks of Adobe Systems Incorporated.

DUNS is a registered trademark of Dun & Bradstreet. 

ãCopyright 2013 United States Postal Service


 

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

2.1.4     Request Example. 17

2.2           Signature Confirmation Response. 19

2.2.1     Response Diagram.. 19

2.2.2     Response Parameters. 21

2.2.3     Response Example. 23


 

1      Introduction

This document contains a Reference Guide to the Signature Confirmation APIs.  See the Developer’s Guide (eCommerce API Technical Guides site

) 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

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=SignatureConfirmationCertifyV4

&XML=(see below)

 

 

   

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

Optional

Indicates that the To address is a PO Box.

boolean

default=false

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

string

enumeration=PDF
enumeration=TIF
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)

 

SignatureConfirmationV4.0Request  / ReturnCommitments

optional

Indicates if commitment information should be returned.

boolean

default=false

SignatureConfirmationV4.0Request  / GroundOnly

optional

Ground Only Indicator for Standard Post

boolean

default=false

SignatureConfirmationV4.0Request    / Content

optional

Special Contents of package

(group)

 

SignatureConfirmationV4.0Request    / Content / ContentType

required once – if content included

Type of content

string

enumeration=HAZMAT
enumeration=LIVES

SignatureConfirmationV4.0Request / Content / ContentDescription

optional

Description. Required if LIVES.

string

enumeration=Bees
enumeration=DayOldPoultry

enumeration=AdultBirds

enumeration=Other

SigConfirmCertifyV4.0Request

required once

 

(alias)

 

 


2.1.4     Request Example

 

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

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

  <Revision>2</Revision>

  <ImageParameters />

  <FromName>John Doe</FromName>

  <FromFirm>USPS</FromFirm>

  <FromAddress1>RM 2100</FromAddress1>

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

  <FromCity>Washington</FromCity>

  <FromState>DC</FromState>

  <FromZip5>20260</FromZip5>

  <FromZip4/>

  <ToName>Janice Dickens</ToName>

  <ToFirm>XYZ Corporation</ToFirm>

  <ToAddress1>Ste 100</ToAddress1>

  <ToAddress2>2 Massachusetts Ave NE</ToAddress2>

  <ToCity>Washington</ToCity>

  <ToState>DC</ToState>

  <ToZip5>20212</ToZip5>

  <ToZip4 />

  <ToPOBoxFlag></ToPOBoxFlag>

  <WeightInOunces>10</WeightInOunces>

  <ServiceType>Priority</ServiceType>

  <SeparateReceiptPage>False</SeparateReceiptPage>

  <POZipCode>20770</POZipCode>

  <ImageType>TIF</ImageType>

  <AddressServiceRequested>False</AddressServiceRequested>

  <HoldForManifest>N</HoldForManifest>

  <Container>NONRECTANGULAR</Container>

  <Size>LARGE</Size>

  <Width>7</Width>

  <Length>20.5</Length>

  <Height>15</Height>

  <Girth>60</Girth>

  <ReturnCommitments>true</ReturnCommitments>

 </SigConfirmCertifyV4.0Request>

 

 

 


2.2    Signature Confirmation Response

2.2.1     Response Diagram


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


 

2.2.2     Response Parameters

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

SignatureConfirmationV4.0Response / Commitment

optional

Returned if ReturnCommitments is true in the request.

(group)

SignatureConfirmationV4.0Response / Commitment / CommitmentName

optional

Commitment name such as 1-day, 2-day, 3-day, Military, DPO

String

SignatureConfirmationV4.0Response / Commitment / ScheduledDeliveryDate

optional

Date in the YYYY-MM-DD format.

date

SigConfirmCertifyV4.0Response

required once

 

(alias)

 


2.2.3     Response Example

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

  <SigConfirmCertifyV4.0Response>

   <SignatureConfirmationNumber>4202077094108XXXXXXXXXXXXXXXXX</SignatureConfirmationNumber>

<SignatureConfirmationLabel>

  SUkqAAgAAAASAP4ABAABAAAAAAAAAAA...

<!--Truncated   -->

</SignatureConfirmationLabel>

    <ToName>JANICE DICKENS</ToName>

    <ToFirm>XYZ CORPORATION</ToFirm>

    <ToAddress1>STE 100</ToAddress1> 

    <ToAddress2>2 MASSACHUSETTS AVE NE</ToAddress2>

    <ToCity>WASHINGTON</ToCity>

    <ToState>DC</ToState>

    <ToZip5>20212</ToZip5>

    <ToZip4>0002</ToZip4>

    <Postnet>2021200202</Postnet>

    <RDC>0024</RDC>

    <Postage>5.60</Postage>

    <Zone>1</Zone>

    <InsuranceFee>0</InsuranceFee>

    <CarrierRoute>C000</CarrierRoute>

       <Commitment>

       <CommitmentName>2-Day</CommitmentName>

       <ScheduledDeliveryDate>2013-07-26</ScheduledDeliveryDate>

   </Commitment>

 

  </SigConfirmCertifyV4.0Response>