USPS Tracking / Delivery
Confirmation
Label

 API

 

USPS Web Tools™

Application Programming Interface

User Guide

Version 5.4 (01/17/2015)

 

 

 

 

 


 

 


Contents

Introduction to Web Tools. 3

Before you get started: 3

USPS Tracking/Delivery Confirmation Label API. 3

Overview.. 3

API Signature. 4

Request Descriptions. 4

Customs forms and data requirements. 17

Sample Request 25

Response Descriptions. 29

Sample Response. 30

Error Responses. 31

 


Introduction to Web Tools

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

 

Note: The Request Parameter sections present the XML input tags for generating live requests along with the restrictions on the values allowed. An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not (*) be generated. The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response. 

 

When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered.  Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values. For instance, a line of sample code may be:

 

<TrackID> EJ123456780US </TrackID>

 

In this instance, you will replace “EJ123456780US” with the tracking ID for the package.

 

(*) Note: The exception regarding error messages is the <ToFirm> tag, which will result in an error if the tag exceeds 32 characters.

Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Technical Documentation section of the Web Tools page on usps.com/webtools.

Label APIs require extra permissions; contact the Internet Customer Care Center (uspstechnicalsupport@mailps.custhelp.com) to request access. Indicate “Label API Access” in the subject line and explain in the body of the email:

1.       How the shipper intends to purchase and apply postage to the labels

2.       If the label image provided by the API will be modified in any way by the shipper or the software

USPS Tracking/Delivery Confirmation Label API

Overview

The USPS Tracking/Delivery Confirmation Label Web Tool generates a label (and accompanying barcode and 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. Please note that the API labels are printed without postage. Postage must be purchased and applied separately. For more information on postage payment methods, see https://www.usps.com/business/postage-options.htm.

 

Visit Domestic Mail Manual for USPS Tracking/Delivery Confirmation information.

 

Postage is required on these labels, as well as the Confirmation Services charge (known as the "electronic option rate") for USPS Tracking/Delivery Confirmation.  This discounted "electronic option rate" for Confirmation Services must be added into the total postage amount affixed to these labels (by using stamps, meter strips, or other indicia).  The USPS Tracking/Delivery Confirmation fee varies by different service and is significantly discounted. 

 

API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=DeliveryConfirmationV4

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=DelivConfirmCertifyV4

&XML=(see below)

 

Note: The “DelivConfirmCertifyV4” API signature is for testing purposes and will not generate usable labels and barcodes.

Request Descriptions

Tag Name

Occurs

Description

Type

Validation

DeliveryConfirmationV4.0Request

required once

DelivConfirmCertifyV4.0Request

 

The "Certify" form of the request is used for integrator testing. It produces a label that is not suitable for mailing and must not be entered into the US Postal System. Certify requests do not require additional permissions to invoke.  

(group)

 

 

 

DeliveryConfirmationV4.0Request / @USERID

required

This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID. 

string

 

DeliveryConfirmationV4.0Request / Option

optional

This tag is for future use.  

empty

 

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

 

DeliveryConfirmationV4.0Request / ImageParameters

optional, 1 time

Enumeration of image parameter to return barcode only image.  

string

minOccurs=0 maxOccurs="unbounded"

DeliveryConfirmationV4.0Request / ImageParameters / ImageParameter

optional, up to 2 times

Returns alternate barcode only label image.

 

“BARCODE ONLY” label option returns a barcode and Package ID Code (PIC) number without the return and delivery name and address.

 

“CROP” reduces the image size to half-sheet (approximately)

 

“SEPARATECONTINUEPAGE” will force the continuation page (if the item count causes the need for a continuation page) onto a separate page.

 

For example: <ImageParameter>BARCODE ONLY</ImageParameter> 

string

Enumerations:

BARCODE ONLY
CROP

SEPARATECONTINUEPAGE

DeliveryConfirmationV4.0Request / ImageParameters / LabelSequence

optional

To be used in the case of multiple packages.   Not required if only one package.

string

minOccurs=0

maxOccurs="1"

DeliveryConfirmationV4.0Request / ImageParameters / LabelSequence /PackageNumber

Required if…

Required if Label Sequence is selected

integer

minInclusive value = "1"

maxInclusive value = "999"

DeliveryConfirmationV4.0Request / ImageParameters / LabelSequence/ TotalPackages

Required if…

Required if Label Sequence is selected

integer

minInclusive value = "1"

maxInclusive value = "999"

DeliveryConfirmationV4.0Request / FromName

Required Tag/ Required Value

Values for either First and Last Name of Sender.

For example: <FromName>John Doe</FromName>

string

minLength=0
maxLength=100 

DeliveryConfirmationV4.0Request / FromFirm

Required Tag/

Value optional

Firm name; may be left blank.

For example: <FromFirm></FromFirm>

string

minLength=0
maxLength=50 

DeliveryConfirmationV4.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=50

DeliveryConfirmationV4.0Request / FromAddress2

required once

Use this tag for the primary address line.

 

For example: <FromAddress2>10 Elm Street </FromAddress2>

string

minLength=1

maxLength=50

DeliveryConfirmationV4.0Request / FromCity

required once

For example: <FromCity>Anytown</FromCity>

string

minLength=1
maxLength=28 

DeliveryConfirmationV4.0Request / FromState

required once

Use 2-letter USPS abbreviation.

 

For example: <FromState>ST</FromState>

string

 

pattern=\w{2}

valid state

 

minLength=2

maxLength=2

DeliveryConfirmationV4.0Request / FromZip5

required once

Input tag exactly as presented, not all caps. 5 digits required.

 

For example: <FromZip5>01234</FromZip5>

string

pattern=\d{5}  

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

DeliveryConfirmationV4.0Request / ToName

required once

Enter a value for the recipient's name.

 

For example: <ToName>Ms. C. P. Apple</ToName>

string

minLength=0

maxLength=100 

DeliveryConfirmationV4.0Request / ToFirm

required once

Enter a value for the recipient's firm.

 

For example: <ToFirm></ToFirm>

string

minLength=0
maxLength=50

DeliveryConfirmationV4.0Request / ToAddress1

required once

Recipient address line 1. Use this tag for an apartment or suite number.  

 

For example: <ToAddress1/>

string

minLength=0
maxLength=50 

DeliveryConfirmationV4.0Request / ToAddress2

required once

Recipient address line 2. Must be a valid address.  

 

For example: <ToAddress2>123 Main Ave </ToAddress2>

string

minLength=0

maxLength=50

DeliveryConfirmationV4.0Request / ToCity

required once

Recipient city.

 

For example: <ToCity>Anytown</ToCity>

string

minLength=0
maxLength=28

DeliveryConfirmationV4.0Request / ToState

required once

Recipient state. Use 2-letter USPS abbreviation.

 

For example: <ToState>ST</ToState>

string

pattern=\w{2}

valid state

 

minLength=2

maxLength=2

DeliveryConfirmationV4.0Request / ToZip5

required once

Recipient ZIP code.

 

For example: <ToZip5>01234</ToZip5>

string

maxLength=5

DeliveryConfirmationV4.0Request / ToZip4

required once

Recipient ZIP+4 extension.  

 

For example: <ToZip5>01234</ToZip5>

string

minLength=0

maxLength=4

DeliveryConfirmationV4.0Request / ToPOBoxFlag

optional

Indicates that the To address is a PO Box.

string

minLength=0

DeliveryConfirmationV4.0Request / ToContactPreference

optional

This indicates how the recipient will be notified that the package is available for pickup. Specify WAIVED if notification is not desired.

 

For example: <ToContactPreference>EMAIL</ToContactPreference>

string

Enumerations:

EMAIL

SMS

WAIVED

 

default=EMAIL

DeliveryConfirmationV4.0Request / ToContactMessaging

optional

This contains the email address or the text messaging address or is blank depending on the ToContactPreference tag. If the EMAIL or SMS enumeration is used in ToContactPreference, this value must be a syntactically-valid e-mail address. If WAIVED is used, this value must be blank.

 

For example: <ToContactMessaging>user@anydomain.gov</ToContactMessaging>

string

maxLength=64

 

DeliveryConfirmationV4.0Request / ToContactEMail

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:

<ToContactEMail>John.Smith@abc.com</ToContactEMail>

string

minLength=0
valid email address

DeliveryConfirmationV4.0Request / WeightInOunces

required once

Required for postage calculation and manifest record.  

 

For example: <WeightInOunces>25

</WeightInOunces>

Integer/decimal

 

DeliveryConfirmationV4.0Request / ServiceType

required once

Mail service type desired.

 

For example: <ServiceType> PRIORITY </ServiceType>

 

Note: Mailable matter not required to be mailed as First-Class Mail is permitted with Standard Post to Zones 5-9. Zones 1-4 items are limited to mailable hazardous materials, live animals, and other “surface-only” items. Standard Post can only be used for Zones 5-9 unless the shipment is oversized or contains classes of materials. (e.g. certain HAZMAT) For more details, see: http://pe.usps.com/businessmail101/classes/packageServices.htm

string

Enumerations:

PRIORITY
FIRST CLASS
RETAIL GROUND
MEDIA MAIL
LIBRARY MAIL  

DeliveryConfirmationV4.0Request / InsuredAmount

optional

Use this tag for entering an insurance amount, if applicable.

 

For example: <InsuredAmount>100.00

</InsuredAmount> 

string

minOccurs=0

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

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

minOccurs=0

 

Enumerations:

true

false

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

minOccurs=0

DeliveryConfirmationV4.0Request / ImageType

required once

Label Image Type.  

 

For example: <ImageType>TIF</ImageType>

string

 

Enumerations:

TIF

PDF

NONE

 

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

 

yyyy-mm-dd

dd-mmm-yyyy, such as 10-Jan-2010, or

mm/dd/yyyy, such as 01/10/2010.

 

For example:

<LabelDate>2015-05-05 </LabelDate>

string

minOccurs=0

pattern=yyyy-mm-dd

pattern=mm\dd\yyyy

pattern= dd-mmm-yyyy

DeliveryConfirmationV4.0Request / CustomerRefNo

optional

User-assigned Number for Internal Use.  

 

For example:

<CustomerRefNo>123456

</CustomerRefNo>

string

minOccurs=0

DeliveryConfirmationV4.0Request / AddressServiceRequested

optional

You can request the USPS to alert you when a customer changes their address. This feature is 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>

 

minOccurs=0

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

minOccurs=0

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

minOccurs=0

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

minOccurs=0

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

minOccurs=0

DeliveryConfirmationV4.0Request / AllowNonCleansedDestAddr

optional

Value of 'true' bypasses destination address cleansing.  Non-cleansed destination addresses may result in undeliverable packages.

string

default=false

 

enumeration=

true

false

DeliveryConfirmationV4.0Request / HoldForManifest

optional

Restricted use. Holds manifest record for possible inclusion in SCAN request.

string

minOccurs=0

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

Enumerations:

·      VARIABLE

·      FLAT RATE ENVELOPE

·      LEGAL FLAT RATE ENVELOPE

·      PADDED FLAT RATE ENVELOPE

·      GIFT CARD FLAT RATE ENVELOPE

·      SM FLAT RATE ENVELOPE

·      WINDOW FLAT RATE ENVELOPE

·      SM FLAT RATE BOX

·      MD FLAT RATE BOX

·      LG FLAT RATE BOX

·      REGIONALRATEBOXA

·      REGIONALRATEBOXB

·      RECTANGULAR

·      NONRECTANGULAR

 

default=VARIABLE

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

Enumerations:

REGULAR

LARGE

DeliveryConfirmationV4.0Request / Width

optional

Value must be numeric. Units are inches. Required when Size is LARGE.

For example: <Width>5.5</Width> 

decimal

minOccurs=0

DeliveryConfirmationV4.0Request / Length

optional

Value must be numeric. Units are inches. Required when Size is LARGE.

For example: <Length>11</Length> 

decimal

minOccurs=0

DeliveryConfirmationV4.0Request / Height

optional

Value must be numeric. Units are inches. Required when Size is LARGE.

For example: <Height>11</Height> 

decimal

minOccurs=0

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

minOccurs=0

DeliveryConfirmationV4.0Request / Machinable

optional

Machinable is required when: ServiceType = ‘ParcelPost’

For example: <Machinable>true</Machinable> 

boolean

minOccurs=0

DeliveryConfirmationV4.0Request / CommercialPrice

optional

Indicates if commercial price should be returned.

 

For example: <CommercialPrice>False

</CommercialPrice>

boolean

minOccurs=0

 

default=false

DeliveryConfirmationV4.0Request / ExtraServices

optional

 

(group)

minOccurs=0 maxOccurs="unbounded"

DeliveryConfirmationV4.0Request / ExtraServices / ExtraService

optional, repeating up to unbounded times

Use to specify extra services.  Currently available services are:

Service Name

ServiceID

Insurance (Non-Priority)

100

Adult Signature Required

119

Adult Signature Restricted Delivery

120

Insurance (Priority)

125

USPS Tracking

155

Signature Confirmation Electronic Restricted Delivery

174

Insurance Restricted Delivery

177

Insurance Restricted Delivery (Priority)

179

For example: <ExtraService>125</ExtraService>

string

Enumerations:

100

119

120

125

155

174

177

179

 

 

 

DeliveryConfirmationV4.0Request  / CarrierRelease

optional

Indicates if the ‘CARRIER – LEAVE IF NO RESPONSE’ is to be printed on the label. This endorsement cannot be applied to Express Mail, Insured items or items requiring a signature at delivery (e.g. Signature Confirmation, Insurance > $200).

 

Use to specify Delivery Preference Codes.  Currently available Delivery Preference Codes are:

Delivery Preference

Code

FRONT DOOR/PORCH 

A

PARCEL LOCKER          

B

PARTNER PARCEL LOCKER  

C

SMART PARCEL LOCKER  

D

LEFT WITH INDIVIDUAL   

E

FRONT DESK/RECEPTION 

F

NEIGHBOR

G

GARAGE AREA 

H

SIDE DOOR/PORCH  

I

BACK DOOR/PORCH     

J

AMAZON PARCEL LOCKER

K

For example: <CarrierRelease>A<CarrierRelease

string

Enumerations:

A

B

C

D

E

F

G

H

I

J

K

true

false

 

 

 

 

 

DeliveryConfirmationV4.0Request / ReturnCommitments

optional

Indicates if commitment information should be returned.

boolean

minOccurs=0 default="false"

DeliveryConfirmationV4.0Request / GroundOnly

optional

Ground Only Indicator for Standard Post

boolean

minOccurs=0 default="false"

DeliveryConfirmationV4.0Request / Content

optional

Special Contents of package

(group)

minOccurs=0 default="false"

DeliveryConfirmationV4.0Request  / ContentType

required once – if content included

Use to specify ContentType.  Available types are:

 

ContentType

HAZMAT

LIVES

PERISHABLE

FRAGILE

 

Required if LIVES.

 

Example: < ContentType >LIVES</ ContentType >

 

Note:  USPS-produced packaging, including Flat Rate and Regional Rate, cannot be used to ship live animals.  Error response will be returned.

string

Enumerations:

HAZMAT 

LIVES

PERISHABLE

FRAGILE

DeliveryConfirmationV4.0Request / ContentDescription

optional

Description. Required if LIVES.

string

Enumerations:

BEES

DAYOLDPOULTRY

ADULTBIRDS

OTHER

Customs forms and data requirements for shipping to/from Military and

Diplomatic (APO/FPO/DPO) and US Possessions, Territories and Freely Associated States (PTFAS)

Please see the below “CustomsContentType” tag for specific customs forms and data requirements and logic.

DeliveryConfirmationV4.0Request  / ShippingContents

required once or optional

Required only if a customs form is required based on Customs Content Type and Weight.

 

(group)

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail

required once repeating up to 30 times or optional

required once repeating up to 30 times if generating an Integrated Customs Form, otherwise not required

 

(group)

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail /Description

Optional/required

Description of the item. Required only if a customs form is required based on Customs Content Type and Weight.

 

For example: <Description>Policy guidelines document</Description>

string

minLength=1

maxLength=256

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail /Quantity

Optional/required

Quantity of the item. Integer value required. Required only if a customs form is required based on Customs Content Type and Weight.

 

For example: <Quantity>1</Quantity>

integer

maxInclusive  value=9

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail / Value

Optional/required

The data entered with this tag provides the value of the set of items. If the item is 2 boxes of 50 pens and the value of each box is $10.00, "20.00" (2 boxes x $10.00) should be entered. If the value of each pen is .25 then "25.00" (100 pens x .25) should be entered. Required only if a customs form is required based on Customs Content Type and Weight.

 

For example: <Value>55.00</Value>

decimal

minExclusive value=0                                                  totalDigits value=8                                                  maxInclusive  value=99999.99

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail / NetPounds

Optional/required

Required to provide the pounds OR ounces component of the weight of the individual item listed with <Description> when a customs form is required based on Customs Content Type and Weight.

 

For example: <NetPounds>1</NetPounds>

integer

totalDigits value=2                                                  minInclusive value=0                                         maxInclusive value=70

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail / NetOunces

Optional/required

Required to provide the ounces OR pounds component of the weight of the individual item listed with <Description> when a customs form is required based on Customs Content Type and Weight.

 

For example: <NetOunces>5</NetOunces>

decimal

totalDigits value=5                                                 minInclusive value=0                                       maxInclusive value=1120

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail / HSTariffNumber

optional

For commercial items only. If known, the HS tariff number must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization.

 

For example: <HSTariffNumber>490110</HSTariffNumber>

string

minLength=0

maxLength=12

DeliveryConfirmationV4.0Request  / ShippingContents / ItemDetail / CountryofOrigin

optional

Country of Origin means the country where the goods originated, e.g. were produced, manufactured, or assembled. It is recommended you supply this information and attach an invoice to the outside to accelerate customs clearance in processing the items. The country name entered must match an entry from the USPS-approved International Index of Countries (see http://pe.usps.com/text/imm/immctry.htm) and Localities or be "United States".

 

For example: <CountryOfOrigin>United States</CountryOfOrigin>

string

minLength=0

maxLength=100

DeliveryConfirmationV4.0Request / FromPhone

optional

10 digits required (including area code), with no punctuation. Use format: 2125551234

 

For example: <FromPhone>5555555555</FromPhone>

string

minOccurs=0

 

whiteSpace=collapse
length=10
pattern=\d{10}

DeliveryConfirmationV4.0Request / SenderMID

optional

Mailer Identification Number.  The MID is a six- or nine-digit number.

string

minOccurs=0

 

minLength=6

maxLength=9

DeliveryConfirmationV4.0Request / ToPhone

optional

10 digits required (including area code), with no punctuation. Use format: 2125551234

 

For example: <ToPhone>5555555555</ToPhone>

string

minOccurs=0

 

whiteSpace=collapse
length=10
pattern=\d{10}

DeliveryConfirmationV4.0Request / CustomsContentType

required

Specifies the content of the package or envelope.

For example: <ContentType>DOCUMENTS</ContentType>

When sending TO or FROM an APO/FPO/DPO or PTFAS, additional Customs information is required.  This requirement is triggered when

·         The “eVSRequest/ ToState” is an APO/FPO/DPO or PTFAS

·         The “eVSRequest/POZipCode” is specified and is an APO/FPO/DPO or PTFAS

·         The “eVSRequest/POZipCode” is NOT specified and The “eVSRequest/ FromState” is an APO/FPO/DPO or PTFAS

 

When one of the above conditions occurs, The Customs Content Type tag is required.  If the Content Type is “DOCUMENTS” and the “WeightInOunces” is specified and is less than 16 oz. no additional Customs tags are required from this section.

string

minOccurs=0

 

enumeration=

MERCHANDISE

GIFT

DOCUMENTS

SAMPLE

RETURN

OTHER

HUMANITARIAN

DANGEROUSGOODS

DeliveryConfirmationV4.0Request  / ContentComments

required / optional

Required tag if <CustomsContentType> =Other

 

Enter any comments. For example: <Comments></Comments>

string

minOccurs=0

DeliveryConfirmationV4.0Request  / RestrictionType

optional

Restriction Types

string

minOccurs=0

 

Enumeration=

Quarantine

Sanitary Inspection

Phytosanitary Inspection

Other

DeliveryConfirmationV4.0Request  / RestrictionComments

Optional

Restriction Comments.  Required when <RestrictionType>="Other”

string

minOccurs=0

DeliveryConfirmationV4.0Request  / AESITN

optional

AES/TN Exemption is a code that indicates the reason why you did not need to file electronic export information

string

minOccurs=0

DeliveryConfirmationV4.0Request  / ImportersReference

optional

Use tag when ServiceType is equal to Priority

 

Importers Reference.  The Importer’s Reference might be a tax code, importer code, or VAT number used for sales tax

string

minOccurs=0

DeliveryConfirmationV4.0Request  / ImportersContact

optional

Use tag  when ServiceType is equal to Priority

 

Importers Contact.  Enter, if known, the Importer’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / ExportersReference

optional

Use tag when ServiceType is equal to Priority

 

Exporters Reference.  The Exporter’s Reference might be a tax code, importer code, or VAT number used for sales tax

string

minOccurs=0

DeliveryConfirmationV4.0Request  / ExportersContact

optional

Use tag when ServiceType is equal to Priority

 

Exporters Contact.  Enter, if known, the Exporter’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / InvoiceNumber

optional

Use tag when ServiceType is equal to Priority

 

Invoice Number

string

minOccurs=0

DeliveryConfirmationV4.0Request  / LicenseNumber

optional

Use tag when ServiceType is equal to Priority

 

License Number

string

minOccurs=0

DeliveryConfirmationV4.0Request  / CertificateNumber

optional

Use tag – when ServiceType is equal to Priority

 

Certificate Number

string

minOccurs=0

DeliveryConfirmationV4.0Request  / NonDeliveryOption

optional

In case package is undeliverable, enter one of the following: "RETURN" for package to be returned to <FromAddress> above. "REDIRECT" to return package to address specified in the below tags. "ABANDON" to dispose of undeliverable package.

 

For example: <NonDeliveryOption>RETURN</NonDeliveryOption>

string

enumeration=RETURN
enumeration=REDIRECT
enumeration=ABANDON

DeliveryConfirmationV4.0Request  / AltReturnAddress1

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is for an apartment or suite number.  

 

For example: <AltReturnAddress1>Apt 1</AltReturnAddress1>

 

Note:

1. Six AltReturnAddress lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / AltReturnAddress2

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the Recipient address line 2. Must be a valid address.  

 

For example: <AltReturnAddress2>123 Main Ave </ AltReturnAddress2>

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / AltReturnAddress3

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the Recipient city.

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / AltReturnAddress4

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the Recipient state. Use 2-letter USPS abbreviation.

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / AltReturnAddress5

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the recipient ZIP code.

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / AltReturnAddress6

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the recipient ZIP+4 extension  

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

DeliveryConfirmationV4.0Request  / AltReturnCountry

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Country.  Tag must equal United States for this API.

string

minOccurs=0

DeliveryConfirmationV4.0Request

required once

 

(alias)

substitutionGroup=

"DelConfirmCertifyV4.0Request"

 

Sample Request

Test XML Request - Standard without generating Military / PTFAS Integrated Customs Form:

https://secure.shippingapis.com/ShippingAPI.dll?API=DelivConfirmCertifyV4&<?xml version="1.0" encoding="UTF-8" ?>

<DelivConfirmCertifyV4.0Request USERID="XXXXXX">

  <Option>1</Option>

  <ImageParameters>

    <LabelSequence>

      <PackageNumber>1</PackageNumber>

      <TotalPackages>99</TotalPackages>

    </LabelSequence>

  </ImageParameters>

  <FromName>Joe Smith</FromName>

  <FromFirm>ABC Corp.</FromFirm>

  <FromAddress1>Apt. 3C</FromAddress1>

  <FromAddress2>6406 Ivy Lane</FromAddress2>

  <FromCity>Greenbelt</FromCity>

  <FromState>MD</FromState>

  <FromZip5>20770</FromZip5>

  <FromZip4>1234</FromZip4>

  <ToName>Tom XofY</ToName>

  <ToFirm>XYZ Corp.</ToFirm>

  <ToAddress1>Suite 4D</ToAddress1>

  <ToAddress2>8 Wildwood Drive</ToAddress2>

  <ToCity>Old Lyme</ToCity>

  <ToState>CT</ToState>

  <ToZip5>06371</ToZip5>

  <ToZip4></ToZip4>

  <WeightInOunces>2</WeightInOunces>

  <ServiceType>Priority</ServiceType>

  <InsuredAmount></InsuredAmount>

  <SeparateReceiptPage></SeparateReceiptPage>

  <POZipCode></POZipCode>

  <ImageType>TIF</ImageType>

  <LabelDate></LabelDate>

  <CustomerRefNo></CustomerRefNo>

  <AddressServiceRequested></AddressServiceRequested>

  <SenderName></SenderName>

  <SenderEMail></SenderEMail>

  <RecipientName></RecipientName>

  <RecipientEMail></RecipientEMail>

  <Container>Variable</Container>

  <Size>Regular</Size>

  <CommercialPrice>True</CommercialPrice>

  <Content>

    <ContentType>LIVES</ContentType>

    <ContentDescription>Bees</ContentDescription>

  </Content>

</DelivConfirmCertifyV4.0Request>

 

Test XML Request – Delivery Confirmation and creating a APO/FPO/DPO or PTFAS Integrated Customs Form:

<DelivConfirmCertifyV4.0Request USERID="XXXXXXXX">

  <Option>1</Option>

  <Revision>2</Revision>

  <ImageParameters>

   <ImageParameter></ImageParameter>

  </ImageParameters>

  <FromName>Dirk Potter</FromName>

  <FromFirm>Dirk Potter's Firm</FromFirm>

  <FromAddress1>126 ShadeTree Road</FromAddress1>

  <FromAddress2>suite #1</FromAddress2>

  <FromCity>Shavertown</FromCity>

  <FromState>PA</FromState>

  <FromZip5>18708</FromZip5>

  <FromZip4></FromZip4>

  <ToName>Builder Bob</ToName>

  <ToFirm>Firm ghijklmnopqrstuvwxyz</ToFirm>

  <ToAddress1></ToAddress1>

  <ToAddress2>>Unit 3300</ToAddress2>

  <ToCity>APO</ToCity>

  <ToState>AE</ToState>

  <ToZip5>09094</ToZip5>

  <ToZip4></ToZip4>

  <ToPOBoxFlag>true</ToPOBoxFlag>

  <WeightInOunces>23</WeightInOunces>

  <ServiceType>PRIORITY</ServiceType>

  <InsuredAmount>1000</InsuredAmount>

  <ImageType>TIF</ImageType>

  <LabelDate></LabelDate>

  <AllowNonCleansedDestAddr></AllowNonCleansedDestAddr>

  <Container>SM FLAT RATE BOX</Container>

  <Size>REGULAR</Size>

  <Width>1</Width>

  <Length>1</Length>

  <Height>1</Height>

  <Girth></Girth>

  <ReturnCommitments>true</ReturnCommitments>

<ShippingContents>

    <ItemDetail>

      <Description>Description 1</Description>

      <Quantity>9999</Quantity>

      <Value>1.11</Value>

      <NetPounds></NetPounds>

      <NetOunces>1</NetOunces>

      <HSTariffNumber>123456789012</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 2</Description>

      <Quantity>2</Quantity>

      <Value>2.22</Value>

      <NetPounds></NetPounds>

      <NetOunces>2</NetOunces>

      <HSTariffNumber>234567</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 3</Description>

      <Quantity>3</Quantity>

      <Value>3.33</Value>

      <NetPounds></NetPounds>

      <NetOunces>3</NetOunces>

      <HSTariffNumber>123456</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 4</Description>

      <Quantity>4</Quantity>

      <Value>4.44</Value>

      <NetPounds></NetPounds>

      <NetOunces>4</NetOunces>

      <HSTariffNumber>234567</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 5</Description>

      <Quantity>5</Quantity>

      <Value>5.55</Value>

      <NetPounds></NetPounds>

      <NetOunces>5</NetOunces>

      <HSTariffNumber>123456</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 6</Description>

      <Quantity>6</Quantity>

      <Value>6.66</Value>

      <NetPounds></NetPounds>

      <NetOunces>6</NetOunces>

      <HSTariffNumber>234567</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

</ShippingContents>

<FromPhone>7175551212</FromPhone>

<SenderMID>123456789</SenderMID>

<ToPhone>5705551212</ToPhone>

<CustomsContentType>Documents</CustomsContentType>

<ContentComments>1234567890123456789012345</ContentComments>

<RestrictionType>Phytosanitary Inspection</RestrictionType>

<RestrictionComments>1234567890123456789012345</RestrictionComments>

<AESITN>12345678901234567890123456789012345</AESITN>

<ImportersReference>123456789012345678901234567890</ImportersReference>

<ImportersContact>Importers Contact: This field can be 50 characters long</ImportersContact>

<ExportersReference>12345678901234</ExportersReference>

<ExportersContact>Exporters Contact: This field can be 50 characters long </ExportersContact>

<InvoiceNumber>Invoice89012345</InvoiceNumber>

<LicenseNumber>License Number12</LicenseNumber>

<CertificateNumber>CertificateX</CertificateNumber>

</DelivConfirmCertifyV4.0Request>

 


Response Descriptions

Tag Name

Occurs

Description

Type

DeliveryConfirmationV4.0Response / DeliveryConfirmationNumber

required once

USPS Tracking/Delivery Confirmation tracking number

string

DeliveryConfirmationV4.0Response / DeliveryConfirmationLabel

required once

USPS Tracking/Delivery Confirmation Label, if requested (where <ImageType> tag not "None") 

base64 Binary

DeliveryConfirmationV4.0Response / ToName

required once

Enter a value for the recipient's name.

 

For example: <ToName>Ms. C. P. Apple</ToName>

string

DeliveryConfirmationV4.0Response / ToFirm

required once

Enter a value for the recipient's firm.

 

For example: <ToFirm></ToFirm>

string

DeliveryConfirmationV4.0Response / ToAddress1

required once

Recipient address line 1. Use this tag for an apartment or suite number.  

 

For example: <ToAddress1/>

string

DeliveryConfirmationV4.0Response / ToAddress2

required once

Recipient address line 2. Must be a valid address.  

 

For example: <ToAddress2>123 Main Ave </ToAddress2>

string

DeliveryConfirmationV4.0Response / ToCity

required once

Recipient city.

 

For example: <ToCity>Anytown</ToCity>

string

DeliveryConfirmationV4.0Response / ToState

required once

Recipient state. Use 2-letter USPS abbreviation.

 

For example: <ToState>ST</ToState>

string

DeliveryConfirmationV4.0Response / ToZip5

required once

Recipient ZIP code.

 

For example: <ToZip5>01234</ToZip5>

string

DeliveryConfirmationV4.0Response / ToZip4

required once

Recipient ZIP+4 extension.  

 

For example: <ToZip5>01234</ToZip5>

string

DeliveryConfirmationV4.0Response / ToPOBoxFlag

optional

Indicates that the To address is a PO Box.

boolean

DeliveryConfirmationV4.0Response / Postnet

required once

 

string

DeliveryConfirmationV4.0Response / RDC

optional repeating up to 1 times

Retail Distribution Code

string

DeliveryConfirmationV4.0Response / Postage

optional

Amount of Postage Required  

decimal

DeliveryConfirmationV4.0Response / Zone

optional

Postal Zone. Indicates the number of postal rate zones between the origin and destination ZIP codes.  

string

DeliveryConfirmationV4.0Response / InsuranceFee

optional

 

string

DeliveryConfirmationV4.0Response / CarrierRoute

optional

Carrier Route

string

DeliveryConfirmationV4.0Response / CarrierRelease

optional

 

boolean

DeliveryConfirmationV4.0Response / ExtraServices

optional

Group of extra services

(group)

DeliveryConfirmationV4.0Response / ExtraService

optional, unbounded times

Groups information for each extra service

(group)

DeliveryConfirmationV4.0Response / ServiceID

required once

Extra Service ID echoed from request

string

DeliveryConfirmationV4.0Response / ServiceName

required once

Extra Service name

string

DeliveryConfirmationV4.0Response / Price

required once

Extra Service fee 

string

DeliveryConfirmationV4.0Response / Commitment

optional

Returned when <ReturnCommitments> = “true” in the request.

(group)

DeliveryConfirmationV4.0Response / CommitmentName

optional

Commitment name.

 

Example “1-Day”.

string

DelivConfirmCertifyV4.0Response /

ScheduledDeliveryDate

optional

Date in the YYYY-MM-DD format.

string

Sample Response

Test XML Response - Standard without generating Military / PTFAS Integrated Customs Form:

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

<DelivConfirmCertifyV4.0Response>

  <DeliveryConfirmationNumber>420063719405501699320XXXXXXXXX</DeliveryConfirmationNumber>

  <DeliveryConfirmationLabel>SUkqAAgAAAASAP4ABAAB

    <!-- over 10000 suppressed -->

  </DeliveryConfirmationLabel>

  <ToName>TOM XOFY</ToName>

  <ToFirm>XYZ CORP.</ToFirm>

  <ToAddress1>STE 4D</ToAddress1>

  <ToAddress2>8 WILDWOOD DR</ToAddress2>

  <ToCity>OLD LYME</ToCity>

  <ToState>CT</ToState>

  <ToZip5>06371</ToZip5>

  <ToZip4>1844</ToZip4>

  <Postnet>06371184408</Postnet>

  <RDC>0006</RDC>

  <Postage>5.23</Postage>

  <Zone>3</Zone>

  <InsuranceFee>0</InsuranceFee>

  <CarrierRoute>R###</CarrierRoute>

</DelivConfirmCertifyV4.0Response>

 

Test XML Response – Delivery Confirmation and creating a APO/FPO/DPO or PTFAS Integrated Customs Form:

<?xml version="1.0"?>

-<DelivConfirmCertifyV4.0Response>

<DeliveryConfirmationNumber>420090949406101699320XXXXXXXX</DeliveryConfirmationNumber>

<DeliveryConfirmationLabel>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBA

    <!-- over 10000 suppressed -->

  </DeliveryConfirmationLabel>

<ToName>Builder Bob</ToName>

<ToFirm>FIRM GHIJKLMNOPQRSTUVWXYZ</ToFirm>

<ToAddress1/>

<ToAddress2>UNIT 3300</ToAddress2>

<ToCity>APO</ToCity>

<ToState>AE</ToState>

<ToZip5>09094</ToZip5>

<ToZip4>3300</ToZip4>

<Postnet>09094330099</Postnet>

<RDC>0004</RDC>

<Postage>5.95</Postage>

<Zone>1</Zone>

<InsuranceFee>14.65</InsuranceFee>

<CarrierRoute>C000</CarrierRoute>

<Commitment>

<CommitmentName>Military</CommitmentName>

<ScheduledDeliveryDate/>

</Commitment>

</DelivConfirmCertifyV4.0Response>

 

Error Responses

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

An <Error> element may be returned at the top (response) level if there is a problem with the syntax of the request, or if a system error occurs.

If you need assistance with an error response, contact the contact our Internet Customer Care Center (uspstechnicalsupport@mailps.custhelp.com)