Express Mail Label

API

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 3.3 (01/17/2016)

 

 

 

 

 

 

United States Postal Service Logo 

 

 


 


Contents

Introduction to Web Tools. 3

Before you get started: 3

1.       USPS Priority Mail Express Label API. 3

1.1.      Overview.. 3

1.2.      API Signature. 4

2.       Tag Descriptions. 4

2.1.      Request Parameters. 4

2.1.1.       Customs forms and data requirements. 13

2.2.      Sample Request 21

2.3.      Response Parameters. 24

2.4.      Sample Response. 27

3.       Error Responses. 28

4.       Label Examples. 29

4.1.      Label Example with Customs Form.. 30


Introduction to Web Tools

This document contains a Reference Guide to the Priority Mail Express 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:

 

<ZipDestination>12345</ZipDestination>

 

In this instance, you will replace “12345” with the destination ZIP Code for the domestic-bound package.

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 API access requires 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

1.  USPS Priority Mail Express Label API

1.1.    Overview

The Priority Mail Express Label API will let customers create Priority Mail Express Labels. Please note that the API labels are printed without postage. Postage must be purchased and applied separately.

 

1.2.    API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=ExpressMailLabel

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=ExpressMailLabelCertify

&XML=(see below)

 

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

2.  Tag Descriptions

2.1.              Request Parameters

Tag Name

Occurs

Description

Type

Validation

ExpressMailLabelRequest

required once

API=ExpressMailLabel  

(group)

 

ExpressMailLabelRequest / @USERID

required

 

NMTOKEN

 

ExpressMailLabelRequest / Option

required once

For future use.  

empty

 

ExpressMailLabelRequest / Revision

optional

In this API use a value of 2 to trigger new functionality.

For example: <Revision>2</Revision>

string

minLength=0
pattern=\d{1}
pattern=  

ExpressMailLabelRequest / EMCAAccount

required

For future use.  

empty

 

ExpressMailLabelRequest / EMCAPassword

required

For future use.  

empty

 

ExpressMailLabelRequest / ImageParameters

optional

 

(group)

 

ExpressMailLabelRequest / ImageParameters / LabelSequence

Optional

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

string

minOccurs="0" maxOccurs="1"

ExpressMailLabelRequest / ImageParameters / LabelSequence /PackageNumber

Required if…

Required if Label Sequence is selected

integer

minInclusive value = "1"

maxInclusive value = "999"

ExpressMailLabelRequest / ImageParameters / LabelSequence/ TotalPackages

Required if…

Required if Label Sequence is selected

integer

minInclusive value = "1"

maxInclusive value = "999"

ExpressMailLabelRequest / ImageParameters/ImageParameter

optional

Forces a Separate Continuation Page when the item count is greater than five.

 

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

 

For example: <ImageParameter> SEPARATECONTINUEPAGE

</ImageParameter>     

string

Enumeration=

SEPARATECONTINUEPAGE

 

ExpressMailLabelRequest / FromFirstName

required once

Values for either First and Last Name of Recipient or Firm must be sent.

 

string


minLength=0  

maxLength=50

ExpressMailLabelRequest / FromLastName

required once

Values for either First and Last Name of Sender or Firm must be sent.


For example: <FromLastName>MARTIAN</FromLastName> 

string

minLength=0
maxLength=50  

ExpressMailLabelRequest / FromFirm

required once

Values for either First and Last Name of Sender or Firm must be sent.


For example: <FromFirm>USPS</FromFirm> 

string

minLength=0
maxLength=50

ExpressMailLabelRequest / FromAddress1

required once

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


For example: <FromAddress1>STE 150</FromAddress1> 

string

minLength=0
maxLength=50  

ExpressMailLabelRequest / FromAddress2

required once

From address line 2.

For example: <FromAddress2>6600 ROCKLEDGE DR</FromAddress2> 

string

minLength=1
maxLength=50 

ExpressMailLabelRequest / FromCity

required once

From city.


For example: <FromCity>BETHESDA</FromCity> 

string

minLength=1
maxLength=28  

ExpressMailLabelRequest / FromState

required once

From state.


For example: <FromState>MD</FromState> 

string

minLength=2
maxLength=2  

ExpressMailLabelRequest / FromZip5

required once

From ZIP code.


For example: <FromZip5>20212</FromZip5> 

string

pattern=\d{5}  

ExpressMailLabelRequest / FromZip4

required once

From ZIP+4 extension.


For example: <FromZip4/> 

string

minLength=0
pattern=\d{4}
pattern=  

ExpressMailLabelRequest / FromPhone

required once

From Phone #. 10 digits required (including area code), with no punctuation.  


For example: <FromPhone>2125551234</FromPhone> 

string

pattern=\d{10}  

ExpressMailLabelRequest / ToFirstName

required once

Values for either First and Last Name of Recipient or Firm must be sent.

 

For example: <ToFirstName>Adam</ToFirstName>

string

minLength=0
maxLength=50  

ExpressMailLabelRequest / ToLastName

required once

Values for either First and Last Name of Recipient or Firm must be sent.

 

For example: <ToLastName>Smith</ToLastName> 

string

minLength=0
maxLength=50  

ExpressMailLabelRequest / ToFirm

required once

Values for either First and Last Name of Recipient or Firm must be sent.

 

For example: <ToFirm>ABC CORPORATION</ToFirm> 

string

minLength=0
maxLength=50  

ExpressMailLabelRequest / ToAddress1

required once

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

 

For example: <ToAddress1/> 

string

minLength=0
maxLength=50  

ExpressMailLabelRequest / ToAddress2

required once

Recipient address line 2. Must be a valid address.  

 

For example: <ToAddress2>1234 MAIN ST</ToAddress2> 

string

minLength=1
maxLength=50  

ExpressMailLabelRequest / ToCity

required once

Recipient city. Unless declined using the <StandardizeAddress> tag the API will cleanse (check) the address using USPS databases. Values for either To City and To State or Zip 5 must be sent.

 

For example: <ToCity>ANYTOWN</ToCity> 

string

minLength=0
maxLength=28

ExpressMailLabelRequest / ToState

required once

Recipient state. Unless declined using the <StandardizeAddress> tag the API will cleanse (check) the address using USPS databases. Values for either To City and To State or Zip 5 must be sent.

 

For example: <ToState>MN</ToState> 

string

minLength=0
pattern=\w{2}

ExpressMailLabelRequest / ToZip5

required once

Recipient ZIP code. Must be a valid ZIP code. Unless declined using the <StandardizeAddress> tag the API will cleanse (check) the address using USPS databases. Values for either To City and To State or Zip 5 must be sent.

 

For example: <ToZip5>12345</ToZip5> 

string

minLength=0
pattern=\d{5}

ExpressMailLabelRequest / ToZip4

required once

Recipient ZIP+4 extension.  

 

For example: <ToZip4/> 

string

minLength=0
pattern=\d{4}

ExpressMailLabelRequest / ToPOBoxFlag

optional

Indicates if the destination address is a PO Box.

 

For example: <ToPOBoxFlag>True</ToPOBoxFlag>

boolean

default=false 

ExpressMailLabelRequest / ToPhone

required once

Recipient Phone #. If value is entered, 10 digits required (including area code), with no punctuation.

 

For example: <ToPhone>2125551234 </ToPhone>

string

pattern=\d{10}

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

whiteSpace=collapse enumeration=EMAIL

enumeration=SMS

enumeration=EMAILSMS

enumeration=WAIVED

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

whiteSpace=collapse

pattern=\w{0}

pattern=([\w_\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}

ExpressMailLabelRequest / 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
pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}

ExpressMailLabelRequest / WeightInOunces

required once

Package weight. Items must weigh 70 pounds or less. 

 

For example: <WeightInOunces>80</WeightInOunces> 

string

pattern=\d{0,4}  

ExpressMailLabelRequest / ShipDate

optional

Deprecated. See "LabelDate" tag.  

string

pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?  

ExpressMailLabelRequest / FlatRate

optional

Deprecated. See "Container" tag.  

boolean

default=false 

ExpressMailLabelRequest / SundayHolidayDelivery

optional

Guaranteed Sunday/Holiday Delivery. When true the label contains special banners and the postage on the label and in the response includes the premium.  

 

For example: <SundayHolidayDelivery/>

boolean

default=false
 

ExpressMailLabelRequest / StandardizeAddress

optional

Delivery Address Cleansed. Enter "true" if you want the API to check the address for accuracy or "false" if you do not.  Parcels with non-standardized addresses run the risk of being undeliverable.

 

For example: <StandardizeAddress/>

boolean

default=true
 

ExpressMailLabelRequest / 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=true 

ExpressMailLabelRequest / CarrierRelease

optional

For future use.  

boolean

minOccurs="0"

ExpressMailLabelRequest / NoHoliday

optional

Deprecated. See "SundayHolidayDelivery" tag.  

boolean

default=false 

ExpressMailLabelRequest / NoWeekend

optional

No Saturday Delivery. Enter "true" if you do not want the package delivered on Saturday or "false" if you do.

boolean

default=false

ExpressMailLabelRequest / 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>true</SeparateReceiptPage>

boolean

default=false
 

ExpressMailLabelRequest / POZipCode

required once

ZIP Code of Post Office or collection box where item is mailed. May be different than From ZIP Code.  

 

For example: <POZipCode/> 

string

minLength=0
pattern=\d{5}

ExpressMailLabelRequest / FacilityType

optional

Has values: "DDU", "SCF", "BMC", "ADC", "ASF". Optional, but cannot be left blank if specified.  

 

For example: <FacilityType>DDU</FacilityType>

string

enumeration=DDU
enumeration=SCF
enumeration=BMC
enumeration=ADC
enumeration=ASF  

ExpressMailLabelRequest / ImageType

required once

Label Image Type.  

 

For example: <ImageType>PDF</ImageType>

string

enumeration=PDF
enumeration=TIF
enumeration=None  

ExpressMailLabelRequest / 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 14-Feb-2011, or mm/dd/yyyy, such as 02/14/2011.  

 

For example: <LabelDate/>  

string

minLength=0
pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?  

ExpressMailLabelRequest / LabelTime

optional

Time Package Will Be Mailed. Time may be midnight (00:00) to 23:59.  Enter the time in the format: HH:MM such as 13:30.


For example: <LabelTime>15:00</LabelTime>

string

minLength=0
pattern=\d{1,2}/:d{2}
pattern=\d{0}

ExpressMailLabelRequest / CustomerRefNo

optional

User-assigned Number for Internal Use.  

 

For example: <CustomerRefNo>XYZ-123</CustomerRefNo>

string

minLength=0
maxLength=30  

ExpressMailLabelRequest / SenderName

optional

Name of E-mail Sender.  

 

For example: <SenderName>C. P. Apple</SenderName>

string

minLength=0  

ExpressMailLabelRequest / SenderEMail

optional

E-mail Address of Sender. Valid e-mail addresses must be used.  

 

For example: <SenderEMail>cpapple@email.com</SenderEMail>  

string

minLength=0
pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}

ExpressMailLabelRequest / RecipientName

optional

Name of E-mail Recipient  

 

For example: <RecipientName/> 

string

minLength=0

ExpressMailLabelRequest / RecipientEMail

optional

E-mail Address of Recipient. Valid e-mail addresses must be used.  

 

For example: <RecipientEMail></RecipientEMail> 

string

minLength=0
pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}

ExpressMailLabelRequest / HoldForManifest

optional

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

string

enumeration=Y
enumeration=N

ExpressMailLabelRequest / CommercialPrice

optional

Indicates if commercial-base price should be returned. For commercial-base price eligibility, please reference the Domestic Mail Manual at http://pe.usps.com/.

 

For example: <CommercialPrice>False

</CommercialPrice>

boolean

default=false 

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

ExpressMailLabelRequest / Container

optional

Use to specify special containers or container attributes that may affect postage; otherwise leave blank.  Required when <Revision>=‘2’.

 

Note: RECTANGULAR or NONRECTANGULAR must be indicated when <Size>LARGE</Size>.


For example: <Container>FLAT RATE ENVELOPE</Container> 

string

whiteSpace=collapse

enumeration=

·      VARIABLE

·      RECTANGULAR

·      NONRECTANGULAR

·      FLAT RATE ENVELOPE

·      LEGAL FLAT RATE ENVELOPE 

·      PADDED FLAT RATE ENVELOPE 

ExpressMailLabelRequest /

Size

optional

Required when <Revision>=’2’. 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=LARGE
enumeration=REGULAR

ExpressMailLabelRequest /

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  

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

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

ExpressMailLabelRequest /

Girth

optional

Value must be numeric. Units are inches. Girth is only required when Container = ‘NONRECTANGULAR’ and Size=’LARGE’.


For example: <Girth>41</Girth> 

decimal

minExclusive=0.0
totalDigits=10  

ExpressMailLabelRequest /

NineDigitRoutingZip

optional

Indicates if an IMPB barcode format is desired.  “True” returns an IMPB barcode with a nine digit routing zip code, and “false” returns and IMPB barcode with a five digit routing zip code.

 

For example: <NineDigitRoutingZip>true</NineDigitRoutingZip> 

boolean

default=false

ExpressMailLabelRequest /

ExtraServices

optional

Groups extra services elements

(group)

 

ExpressMailLabelRequest / ExtraServices / ExtraService

optional, repeating up to unbounded times

Use to specify extra services.  Currently available services are:

 

Service Name

ServiceID

Adult Signature

119

Adult Signature Restricted Delivery

120

 

10:30 AM Delivery (PME)

161

Insurance Restricted Delivery (PME)

178

 

For example: <ExtraService>119</ExtraService>

string

enumeration=119

enumeration=120

enumeration=161

enumeration=178

 

 

ExpressMailLabelRequest / ReturnCommitments

optional

Indicates if commitment information should be returned.

For example: <ReturnCommitments>True</ReturnCommitments>

boolean

default=false 

ExpressMailLabelRequest / Content

optional

Groups Content elements when a special Content is included in the shipment.

(group)

 

ExpressMailLabelRequest / Content / ContentType

required once – if content included

Use to specify ContentType.  Available types are:

 

ContentType

HAZMAT

CrematedRemains

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

Enumeration=

HAZMAT 

CrematedRemains

Lives

Perishable

Fragile

ExpressMailLabelRequest / Content / ContentDescriptor

Optional

Description of contents. Required for ContentType of LIVES

 

For example: <ContentDescriptor>Bees</ContentDescriptor>

string

enumeration=

Bees
DayOldPoultry

AdultBirds

Other

 

2.1.1.   Customs forms and data requirements

for shipping to/from Military and Diplomatic (APO/FPO/DPO) and US Possessions, Territories and Freely Associated States (PTFAS) shipping.

 

Please see the below “CustomsContentType” tag for specific customs forms,

data requirements and logic

ExpressMailLabelRequest / ShippingContents

required once or optional

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

 

(group)

ExpressMailLabelRequest / 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)

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

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

whitespace=collapse

maxInclusive  value=9999

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

ExpressMailLabelRequest / ShippingContents / ItemDetail / NetPounds

optional/required

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

ExpressMailLabelRequest / ShippingContents / ItemDetail / NetOunces

optional/required

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

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

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

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

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

ExpressMailLabelRequest / SenderMID

optional

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

string

minOccurs=0

 

minLength=6

maxLength=9

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

ExpressMailLabelRequest / ContentComments

optional

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

string

minOccurs=0

ExpressMailLabelRequest / RestrictionType

optional

Restriction Types

string

minOccurs=0

 

Enumeration=

Quarantine

Sanitary Inspection

Phytosanitary Inspection

Other

ExpressMailLabelRequest / RestrictionComments

Optional

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

string

minOccurs=0

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

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

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

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

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

ExpressMailLabelRequest / InvoiceNumber

optional

Use tag when ServiceType is equal to Priority

 

Invoice Number

string

minOccurs=0

ExpressMailLabelRequest / LicenseNumber

optional

Use tag when ServiceType is equal to Priority

 

License Number

string

minOccurs=0

ExpressMailLabelRequest / CertificateNumber

optional

Use tag – when ServiceType is equal to Priority

 

Certificate Number

string

minOccurs=0

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

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

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

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

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

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

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

ExpressMailLabelRequest / AltReturnCountry

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Country.  Tag must equal United States for this API.

string

minOccurs=0

ExpressMailLabelRequest

required once

 

(alias)

 

 

2.2.              Sample Request

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

https://production.shippingapis.com/ShippingAPITest.dll?API=ExpressMailLabelRequest2&XML<ExpressMailLabelCertifyRequest  USERID="XXXXXX">

<Option/>

  <Revision>2</Revision>

  <EMCAAccount/>

  <EMCAPassword/>

  <ImageParameters>

    <LabelSequence>

      <PackageNumber>2</PackageNumber>

      <TotalPackages>3</TotalPackages>

    </LabelSequence>

  </ImageParameters>

  <FromFirstName>Bill</FromFirstName>

  <FromLastName>Strong</FromLastName>

  <FromFirm/>

  <FromAddress1></FromAddress1>

  <FromAddress2>6406 Ivy Lane</FromAddress2>

  <FromCity>Greenbelt</FromCity>

  <FromState>MD</FromState>

  <FromZip5>20770</FromZip5>

  <FromZip4></FromZip4>

  <FromPhone>3015551212</FromPhone>

  <ToFirstName>John</ToFirstName>

  <ToLastName>Doe</ToLastName>

  <ToFirm/>

  <ToAddress1>404f</ToAddress1>

  <ToAddress2>3900 Connecticut Ave</ToAddress2>

  <ToCity>Washington</ToCity>

  <ToState>DC</ToState>

  <ToZip5></ToZip5>

  <ToZip4></ToZip4>

  <ToPhone>2025551212</ToPhone>

  <WeightInOunces>55</WeightInOunces>

  <FlatRate></FlatRate>

  <WaiverOfSignature>TRUE</WaiverOfSignature>

  <SeparateReceiptPage></SeparateReceiptPage>

  <POZipCode/>

  <ImageType>GIF</ImageType>

  <HoldForManifest>n</HoldForManifest>

  <CommercialPrice>True</CommercialPrice>

  <InsuredAmount></InsuredAmount>

  <Container>FLAT RATE ENVELOPE</Container>

  <Size>REGULAR</Size>

  <NineDigitRoutingZip>True</NineDigitRoutingZip>

  <ExtraServices>

    <ExtraService>ADULTRESTRICTED</ExtraService>

  </ExtraServices>

  <ReturnCommitments>true</ReturnCommitments>

  </ExpressMailLabelCertifyRequest>

 

Test XML Request – and creating a Military / PTFAS Integrated Customs Form:

https://production.shippingapis.com/ShippingAPITest.dll?API=ExpressMailLabelRequest2&XML<ExpressMailLabelCertifyRequest  USERID="XXXXXX">

<Option/>

  <Revision>2</Revision>

  <EMCAAccount/>

  <EMCAPassword/>

  <ImageParameters>

    <LabelSequence>

      <PackageNumber>2</PackageNumber>

      <TotalPackages>3</TotalPackages>

    </LabelSequence>

  </ImageParameters>

  <FromFirstName>Bill</FromFirstName>

  <FromLastName>Strong</FromLastName>

  <FromFirm/>

  <FromAddress1></FromAddress1>

  <FromAddress2>6406 Ivy Lane</FromAddress2>

  <FromCity>Greenbelt</FromCity>

  <FromState>MD</FromState>

  <FromZip5>20770</FromZip5>

  <FromZip4></FromZip4>

  <FromPhone>3015551212</FromPhone>

  <ToFirstName>John</ToFirstName>

  <ToLastName>Doe</ToLastName>

  <ToFirm/>

  <ToAddress1>404f</ToAddress1>

  <ToAddress2>3900 Connecticut Ave</ToAddress2>

  <ToCity>Washington</ToCity>

  <ToState>DC</ToState>

  <ToZip5></ToZip5>

  <ToZip4></ToZip4>

  <ToPhone>2025551212</ToPhone>

  <WeightInOunces>12</WeightInOunces>

  <FlatRate></FlatRate>

  <WaiverOfSignature>TRUE</WaiverOfSignature>

  <SeparateReceiptPage></SeparateReceiptPage>

  <POZipCode/>

  <ImageType>TIF</ImageType>

  <LabelDate></LabelDate>

  <HoldForManifest>n</HoldForManifest>

  <CommercialPrice>True</CommercialPrice>

  <InsuredAmount>1000</InsuredAmount>

  <Container>VARIABLE</Container>

  <Size>REGULAR</Size>

  <Width>1</Width>

  <Length>1</Length>

  <Height>1</Height>

  <Girth></Girth>

  <NineDigitRoutingZip>True</NineDigitRoutingZip>

  <ExtraServices>

    <ExtraService></ExtraService>

  </ExtraServices>

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

<SenderMID>123456789</SenderMID>

<CustomsContentType>Document</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 chars long</ImportersContact>

<ExportersReference>12345678901234</ExportersReference>

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

<InvoiceNumber>Invoice89012345</InvoiceNumber>

<LicenseNumber>License Number12</LicenseNumber>

<CertificateNumber>CertificateX</CertificateNumber>

</ExpressMailLabelCertifyRequest>

 

2.3.              Response Parameters

Tag Name

Occurs

Description

Type

Validation

ExpressMailLabelResponse

required once

 

(group)

 

ExpressMailLabelResponse / ToFirstName

required once

First Name of Recipient  

string

 

ExpressMailLabelResponse / ToLastName

required once

Last Name of Recipient  

string

 

ExpressMailLabelResponse / ToFirm

required once

Company Name  

string

 

ExpressMailLabelResponse / ToAddress1

required once

To Address Line 1  

string

 

ExpressMailLabelResponse / ToAddress2

required once

To Address Line 2  

string

 

ExpressMailLabelResponse / ToCity

required once

To City  

string

 

ExpressMailLabelResponse / ToState

required once

To State  

string

 

ExpressMailLabelResponse / ToZip5

required once

To ZIP Code  

string

 

ExpressMailLabelResponse / ToZip4

required once

To ZIP Code+4  

string

 

ExpressMailLabelResponse / Postage

required once

Amount of Postage Required, includes amount for fragile special handling if requested,, does not include insurance or other extra service fees.

decimal

 

ExpressMailLabelResponse / EMConfirmationNumber

required once

Priority Mail Express Tracking Number  

string

 

ExpressMailLabelResponse / EMLabel

optional

Priority Mail Express Label, if requested (where <ImageType> tag not "None") 

base64Binary

 

ExpressMailLabelResponse / EMReceipt

optional

Separate Express Mail Customer Online Record, if requested using <SeparateReceiptPage> tag 

base64Binary

 

ExpressMailLabelResponse / RDC

optional repeating up to 1 times

 

string

 

ExpressMailLabelResponse / InsuranceFee

optional

 

decimal

minExclusive=0.0
maxInclusive=5000

ExpressMailLabelResponse / ExtraServices

required once

 

(group)

 

ExpressMailLabelResponse /

Extra Services / Extra Service

optional, repeating up to unbounded times

Groups extra service information

(group)

 

ExpressMailLabelResponse /

Extra Services / Extra Service / ServiceID

required once

Extra Service ID

string

 

ExpressMailLabelResponse /

Extra Services / Extra Service / ServiceName

required once

Extra Service Name

string

 

ExpressMailLabelResponse /

Extra Services / Extra Service / ServiceFee

optional

Extra Service fee 

decimal

 

ExpressMailLabelResponse / Zone

required once

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

string

 

ExpressMailLabelResponse / CarrierRoute

required once

 

string

 

ExpressMailLabelResponse / Commitment

optional

Returned if <ReturnCommitments> is true in the request.

(group)

 

ExpressMailLabelResponse / Commitment / CommitmentName

optional

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

String

 

ExpressMailLabelResponse / Commitment / ScheduledDeliveryDate

optional

Date in the YYYY-MM-DD format.

date

 

ExpressMailLabelResponse / LogMessage

optional

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

 

ExpressMailLabelCertifyResponse

required once

 

(alias)

 


2.4.              Sample Response

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

<?xml version="1.0"?>

<ExpressMailLabelCertifyResponse>

  <ToFirstName>John</ToFirstName>

  <ToLastName>Doe</ToLastName>

  <ToFirm></ToFirm>

  <ToAddress1>APT 404F</ToAddress1>

  <ToAddress2>3900 CONNECTICUT AVE NW</ToAddress2>

  <ToCity>WASHINGTON</ToCity>

  <ToState>DC</ToState>

  <ToZip5>20008</ToZip5>

  <ToZip4>2485</ToZip4>

  <Postage>44.95</Postage>

  <EMConfirmationNumber>42XXXXXXXXXX59</EMConfirmationNumber>

  <EMLabel>R0lGODdhcgZmCIcAAAAA

    <!-- over 115000 suppressed -->

  </EMLabel>

  <RDC>0007</RDC>

  <ExtraServices>

    <ExtraService>

      <ExtraServiceID>20</ExtraServiceID>

      <ExtraServiceName>ADULTRESTRICTED</ExtraServiceName>

      <ExtraServiceFee>5.75</ExtraServiceFee>

    </ExtraService>

  </ExtraServices>

  <Zone>01</Zone>

  <CarrierRoute>C###</CarrierRoute>

  <Commitment>

    <CommitmentName>1-Day</CommitmentName>

    <ScheduledDeliveryDate>20##-##-##</ScheduledDeliveryDate>

  </Commitment>

</ExpressMailLabelCertifyResponse>

 

Test XML Response – and creating a Military / PTFAS Integrated Customs Form:

<?xml version="1.0"?>

<ExpressMailLabelCertifyResponse>

  <ToFirstName>John</ToFirstName>

  <ToLastName>Doe</ToLastName>

  <ToFirm></ToFirm>

  <ToAddress1>APT 404F</ToAddress1>

  <ToAddress2>3900 CONNECTICUT AVE NW</ToAddress2>

  <ToCity>WASHINGTON</ToCity>

  <ToState>DC</ToState>

  <ToZip5>20008</ToZip5>

  <ToZip4>2485</ToZip4>

  <Postage>15.13</Postage>

  <EMConfirmationNumber>42XXXXXXXXXX59</EMConfirmationNumber>

  <EMLabel>R0lGODdhcgZmCIcAAAAA

    <!-- over 115000 suppressed -->

  </EMLabel>

<RDC>0007</RDC>

<InsuranceFee>0.00</InsuranceFee>

<ExtraServices/>

<Zone>01</Zone>

<CarrierRoute>C000</CarrierRoute>

<Commitment>

<CommitmentName>Military</CommitmentName>

<ScheduledDeliveryDate>2015-11-13</ScheduledDeliveryDate>

</Commitment>

</ExpressMailLabelCertifyResponse>

3.  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 our Internet Customer Care Center uspstechnicalsupport@mailps.custhelp.com

 

 

4.  Label Examples

Express Doc Image

 

 

 

 

 

 

 

 

 

 

4.1.              Label Example with Customs Form