USPS Tracking / Delivery Confirmation Label API

(1)

Delivery

Confirmation Label

API

USPS Web Tools™

Application Programming Interface

User Guide

(2)

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

(3)

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:

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

([email protected]) 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.

(4)

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.0Re quest 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.0Re

quest / @USERID required

This attribute specifies your Web

Tools ID. See the Developer's Guide

for information on obtaining your

USERID.

string

DeliveryConfirmationV4.0Re

quest / Option optional This tag is for future use. empty

quest / 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:

string

(5)

Tag Name Occurs Description Type Validation DeliveryConfirmationV4.0Re

quest / ImageParameters

optional,

1 time

Enumeration of image parameter to

return barcode only image. string

minOccurs=0 maxOccurs="unbounded" DeliveryConfirmationV4.0Re quest / 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.0Re quest / ImageParameters / LabelSequence optional

To be used in the case of multiple

packages. Not required if only one

package. string minOccurs=0 maxOccurs="1" DeliveryConfirmationV4.0Re quest / ImageParameters / LabelSequence /PackageNumber Required if…

Required if Label Sequence is

selected integer minInclusive value = "1" maxInclusive value = "999" DeliveryConfirmationV4.0Re quest / ImageParameters / LabelSequence/ TotalPackages Required if…

Required if Label Sequence is

selected integer minInclusive value = "1" maxInclusive value = "999" DeliveryConfirmationV4.0Re quest / 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.0Re quest / FromFirm Required Tag/ Value optional

Firm name; may be left blank.

For example:

string minLength=0

(6)

DeliveryConfirmationV4.0Re quest / 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.0Re quest / FromAddress2 required once

Use this tag for the primary address

line.

For example: <FromAddress2>10

Elm Street </FromAddress2>

string minLength=1 maxLength=50 DeliveryConfirmationV4.0Re quest / FromCity required once For example: <FromCity>Anytown</FromCity> string minLength=1 maxLength=28 DeliveryConfirmationV4.0Re quest / FromState required once

Use 2‐letter USPS abbreviation. For example: <FromState>ST</FromState> string pattern=\w{2} valid state minLength=2 maxLength=2 DeliveryConfirmationV4.0Re quest / FromZip5 required once

Input tag exactly as presented, not

all caps. 5 digits required. For example: <FromZip5>01234</FromZip5> string pattern=\d{5} DeliveryConfirmationV4.0Re quest / 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.0Re quest / 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.0Re quest / ToFirm required once

Enter a value for the recipient's

firm.

For example: <ToFirm></ToFirm>

string minLength=0 maxLength=50 DeliveryConfirmationV4.0Re quest / ToAddress1 required once

Recipient address line 1. Use this tag

for an apartment or suite number.

For example: <ToAddress1/>

string minLength=0

(7)

DeliveryConfirmationV4.0Re quest / 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.0Re quest / ToCity required once Recipient city. For example: <ToCity>Anytown</ToCity> string minLength=0 maxLength=28 DeliveryConfirmationV4.0Re quest / 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.0Re quest / ToZip5 required once

Recipient ZIP code. For example: <ToZip5>01234</ToZip5> string maxLength=5 DeliveryConfirmationV4.0Re quest / ToZip4 required once

Recipient ZIP+4 extension. For example: <ToZip5>01234</ToZip5> string minLength=0 maxLength=4 DeliveryConfirmationV4.0Re

quest / ToPOBoxFlag optional

Indicates that the To address is a PO

Box. string minLength=0

quest / 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</ToC ontactPreference> string Enumerations: EMAIL SMS WAIVED default=EMAIL

(8)

quest / 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@anydo main.gov</ToContactMessaging> string maxLength=64 DeliveryConfirmationV4.0Re

quest / 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.0Re quest / WeightInOunces

required

once

Required for postage calculation

and manifest record.

For example: <WeightInOunces>25

</WeightInOunces> Integer/d ecimal DeliveryConfirmationV4.0Re quest / 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/businessmail10 1/classes/packageServices.htm string Enumerations: PRIORITY FIRST CLASS RETAIL GROUND MEDIA MAIL LIBRARY MAIL

(9)

quest / InsuredAmount optional

Use this tag for entering an

insurance amount, if applicable. For example: <InsuredAmount>100.00 </InsuredAmount> string minOccurs=0 DeliveryConfirmationV4.0Re

quest / 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

quest / 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.0Re

quest / 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.0Re quest / ImageType required once

Label Image Type. For example: <ImageType>TIF</ImageType> string Enumerations: TIF PDF NONE

(10)

quest / 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.0Re

quest / CustomerRefNo optional

User‐assigned Number for Internal

Use. For example: <CustomerRefNo>123456 </CustomerRefNo> string minOccurs=0

(11)

DeliveryConfirmationV4.0Re quest /

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

quest / SenderName optional

The name of the person or

company sending the email.

For example:

<SenderName>John

Smith</SenderName>

(12)

quest / SenderEMail optional

E‐mail address of sender. Valid e‐

generating a Sample Label request. For example: <SenderEMail>[email protected] m </SenderEMail> string minOccurs=0 DeliveryConfirmationV4.0Re

quest / RecipientName optional

The name of the person or company

receiving the email.

For example: <RecipientName>Mary Jones</RecipientName> string minOccurs=0 DeliveryConfirmationV4.0Re

quest / RecipientEMail optional

E‐mail address of recipient. Valid e‐

generating a Sample Label request. For example: <RecipientEMail>[email protected] </RecipientEMail> string minOccurs=0 DeliveryConfirmationV4.0Re quest / 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.0Re

quest / HoldForManifest optional

Restricted use. Holds manifest

record for possible inclusion in

SCAN request.

(13)

quest / 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.0Re

quest / 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.0Re

quest / Width optional

Value must be numeric. Units are

inches. Required when Size is

LARGE.

For example: <Width>5.5</Width>

decimal minOccurs=0

quest / Length optional

LARGE.

For example: <Length>11</Length>

(14)

quest / Height optional

LARGE.

For example: <Height>11</Height>

decimal minOccurs=0

quest / Girth optional

inches. Girth is only required when

Container = ‘NONRECTANGULAR’ or

‘VARIABLE’ and Size=’LARGE’

.

For example: <Girth>11</Girth>

decimal minOccurs=0

quest / Machinable optional

Machinable is required when:

ServiceType = ‘ParcelPost’ For example: <Machinable>true</Machinable> boolean minOccurs=0 DeliveryConfirmationV4.0Re

quest / CommercialPrice optional

Indicates if commercial price should

be returned. For example: <CommercialPrice>False </CommercialPrice> boolean minOccurs=0 default=false DeliveryConfirmationV4.0Re

quest / ExtraServices optional (group)

minOccurs=0

(15)

Tag Name Occurs Description Type Validation DeliveryConfirmationV4.0Re quest / ExtraServices / ExtraService optional, repeating up to unbounde d 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

(16)

quest / 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.0Re

quest / ReturnCommitments optional

Indicates if commitment

information should be returned. boolean minOccurs=0 default="false"

quest / GroundOnly optional

Ground Only Indicator for Standard

Post boolean minOccurs=0 default="false"

(17)

Tag Name Occurs Description Type Validation DeliveryConfirmationV4.0Re quest / 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.0Re

quest / 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.0Re quest / ShippingContents

required

once or

optional

Required only if a customs form is

required based on Customs Content

Type and Weight.

(group) DeliveryConfirmationV4.0Re quest / 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.0Re quest / 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

(18)

Tag Name Occurs Description Type Validation DeliveryConfirmationV4.0Re quest / 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:

integer maxInclusive value=9

DeliveryConfirmationV4.0Re quest / 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.0Re quest / 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.0Re quest / 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

(19)

DeliveryConfirmationV4.0Re quest / 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</HSTariff Number> string minLength=0 maxLength=12 DeliveryConfirmationV4.0Re quest / 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/immc try.htm) and Localities or be "United

States". For example: <CountryOfOrigin>United States</CountryOfOrigin> string minLength=0 maxLength=100 DeliveryConfirmationV4.0Re

quest / FromPhone optional

10 digits required (including area

code), with no punctuation. Use

format: 2125551234 For example: <FromPhone>5555555555</FromPh one> string minOccurs=0 whiteSpace=collapse length=10 pattern=\d{10} DeliveryConfirmationV4.0Re

quest / SenderMID optional

Mailer Identification Number. The

MID is a six‐ or nine‐digit number. string

minOccurs=0

minLength=6

maxLength=9

quest / 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}

(20)

quest / CustomsContentType required

Specifies the content of the package

or envelope.

For example:

<ContentType>DOCUMENTS</Cont entType>

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

 The “eVSRequest/POZipCode” is

NOT specified and The

“eVSRequest/ FromState” is an

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.0Re quest / ContentComments required / optional Required tag if <CustomsContentType> =Other

Enter any comments. For example:

string minOccurs=0

quest / RestrictionType optional Restriction Types string

minOccurs=0 Enumeration= Quarantine Sanitary Inspection Phytosanitary Inspection Other DeliveryConfirmationV4.0Re quest / RestrictionComments

Optional Restriction Comments. Required

(21)

quest / 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.0Re quest / 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.0Re quest / 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

quest / 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

quest / ExportersContact optional

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

quest / InvoiceNumber optional

Use tag when ServiceType is equal to Priority Invoice Number string minOccurs=0 DeliveryConfirmationV4.0Re

quest / LicenseNumber optional

License Number

(22)

Tag Name Occurs Description Type Validation DeliveryConfirmationV4.0Re quest / CertificateNumber optional Use tag – when ServiceType is equal to Priority Certificate Number string minOccurs=0 DeliveryConfirmationV4.0Re

quest / 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</Non DeliveryOption> string enumeration=RETURN enumeration=REDIRECT enumeration=ABANDON DeliveryConfirmationV4.0Re quest / 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.

(23)

Tag Name Occurs Description Type Validation DeliveryConfirmationV4.0Re quest / 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

variation. string minOccurs=0 DeliveryConfirmationV4.0Re quest / AltReturnAddress3 optional Required if NonDeliveryOption tag=REDIRECT.

Recipient city.

Note:

variation.

(24)

abbreviation.

Note:

variation. string minOccurs=0 DeliveryConfirmationV4.0Re quest / AltReturnAddress5 optional Required if NonDeliveryOption tag=REDIRECT.

recipient ZIP code.

Note:

variation.

(25)

recipient ZIP+4 extension

Note:

variation. string minOccurs=0 DeliveryConfirmationV4.0Re quest / AltReturnCountry optional Required if NonDeliveryOption tag=REDIRECT.

Country. Tag must equal United

States for this API.

string minOccurs=0 DeliveryConfirmationV4.0Re quest required once (alias) substitutionGroup= "DelConfirmCertifyV4.0Re quest"

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>

(26)

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

(27)

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

(28)

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

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

<InvoiceNumber>Invoice89012345</InvoiceNumber>

<LicenseNumber>License Number12</LicenseNumber>

<CertificateNumber>CertificateX</CertificateNumber>

(29)

Response Descriptions

Tag Name Occurs Description Type

DeliveryConfirmationV4.0Response /

DeliveryConfirmationNumber

required

once

USPS Tracking/Delivery Confirmation

tracking number string

DeliveryConfirmationLabel

required

once

USPS Tracking/Delivery Confirmation

Label, if requested (where <ImageType>

tag not "None")

base64 Binary

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

ToAddress1

required

once

Recipient address line 1. Use this tag for

an apartment or suite number.

For example: <ToAddress1/>

string

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

ToState

required

once

abbreviation.

For example: <ToState>ST</ToState>

string

ToZip5

required

once

Recipient ZIP code.

For example: <ToZip5>01234</ToZip5>

string

ToZip4

required

once

Recipient ZIP+4 extension.

For example: <ToZip5>01234</ToZip5>

string

ToPOBoxFlag optional Indicates that the To address is a PO Box. boolean

Postnet

required

(30)

Tag Name Occurs Description Type DeliveryConfirmationV4.0Response / RDC optional repeating up to 1 times

Retail Distribution Code string

Postage optional Amount of Postage Required decimal

Zone optional

Postal Zone. Indicates the number of

postal rate zones between the origin and

destination ZIP codes.

string

InsuranceFee optional string

CarrierRoute optional Carrier Route string

CarrierRelease optional boolean

ExtraServices optional Group of extra services (group)

ExtraService

optional, unbounde d times

Groups information for each extra

service (group)

ServiceID

required

once Extra Service ID echoed from request string

ServiceName

required

once Extra Service name string

Price

required

once Extra Service fee string

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>

(31)

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

(32)

<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