International
Shipping Labels

 

USPS Web Tools™

Application Programming Interface

Reference

Document Version 5.0 (2/06/2014)

 

 

 

United States Postal Service Logo
 

 

 

 



To Our Customers

In registering for use of the USPS Web Tools™ (Web Tools), you received a user ID that will allow you to begin sending calls to the server when you are ready.  Any additional information or contact with you will occur as indicated on the registration form, please return to the Web Tools eCommerce API Technical Guides site for the most recent Web Tools API documentation.

If you require technical support, contact the USPS Internet Customer Care Center (ICCC). This office is staffed as follows:

  • Monday through Friday from 8:00 a.m. to 8:30 p.m. Eastern Time 
  • Saturdays from 8:00 a.m. to 6:00 p.m. Eastern Time 
  • Sunday and Postal Holidays - Closed except for the following Holidays: Martin Luther King; President's Day; Columbus Day; & Veteran’s Day with hours from 9:00 a.m. to 6:00 p.m. ET.

 

E-mail address:  uspstechnicalsupport@mailps.custhelp.com

Telephone: 1-800-344-7779

 

USPS Customer Commitment

The United States Postal Service fully understands the importance of providing information and service anytime day or night to your Internet and e-commerce customers.  For that reason, the USPS is committed to providing 24 x 7 service from our Web Tools servers, 365 days a year.

Registered Trademarks

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

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

Microsoft and Visual Basic are registered trademarks of Microsoft Corporation.

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

DUNS is a registered trademark of Dun & Bradstreet.

ãCopyright 2013 United States Postal Service


 

Table of Contents

1       Introduction. 5

2       Priority Mail Express International API 5

2.1           Priority Mail Express International Request 5

2.1.1     API Signature. 5

2.1.2     Request Parameters. 6

2.1.3     Request Example. 19

2.2           Priority Mail Express International Response. 23

2.2.1     Response Parameters. 23

2.2.2     Label Diagram (Full Size) 25

2.2.3     Label Diagram (4x6 Size) 28

2.2.4     Tagged Label Diagram.. 31

2.2.5     Response Example. 32

3       Priority Mail International API 33

3.1           Priority Mail International Request 33

3.1.1     API Signature. 33

3.1.2     Request Parameters. 34

3.1.3     Request Example. 49

3.2           Priority Mail International Response. 52

3.2.1     Response Parameters. 52

3.2.2     Label Diagram (Full Size) 54

3.2.3     Label Diagram (4x6 Size) 57

3.2.4     Tagged Label Diagram.. 60

3.2.5     Response Example. 61

4       First Class Mail International API 62

4.1           First Class Mail International Request 62

4.1.1     API Signature. 62

4.1.2     Request Parameters. 63

4.1.3     Request Example. 74

4.2           First Class Mail International Response. 77

4.2.1     Response Parameters. 77

4.2.2     Label Diagram.. 79

4.2.3     Tagged Label Diagram.. 80

4.2.4     Response Example. 81

 


1     Introduction

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

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

2     Priority Mail Express International API

2.1      Priority Mail Express International Request

The table below presents the XML input tags for generating Live requests and 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.

2.1.1     API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=ExpressMailIntl

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=ExpressMailIntlCertify

&XML=(see below)

 


 

2.1.2     Request Parameters

Tag Name

Occurs

Description

Type

Validation

ExpressMailIntlRequest

required once

 

(group)

 

ExpressMailIntlRequest / @USERID

required

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

string

 

ExpressMailIntlRequest / @PASSWORD

optional

For backward-compatibility; not validated.

string

 

ExpressMailIntlRequest / Option

optional

For future use.

empty

 

ExpressMailIntlRequest / Revision

optional

Use of value 2 required as of January 2011.

 

For example: <Revision>2</Revision>

string

minLength=0

pattern=\d{1}

pattern=

ExpressMailIntlRequest / ImageParameters

optional

Groups alternate image options.

(group)

 

ExpressMailIntlRequest / ImageParameters / ImageParameter

Optional, repeating up to 3 times

Returns alternate label image.  Only alternate 4’’x6’’ size label image may be requested at this time.  

For example: <ImageParameter>4BY6LABEL</ImageParameter> 

empty

Enumeration=4BY6LABEL

ExpressMailIntlRequest / FromFirstName

optional

Both FromFirstName and FromLastName are required if FromFirmName is left blank. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name.

 

For example: <FromFirstName>John</FromFirstName>

string

maxLength=30
minLength=0

Restriction enforced via truncation

ExpressMailIntlRequest / FromMiddleInitial

optional

Middle Initial.  Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name.

 

For example: <FromMiddleInitial>L</FromMiddleInitial>

string

maxLength=1

Restriction enforced via truncation

ExpressMailIntlRequest / FromLastName

optional

Both FromFirstName and FromLastName are required if FromFirmName is left blank. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name.

 

For example: <FromLastName>Doe</FromLastName>

string

maxLength=30
minLength=0

Restriction enforced via truncation

ExpressMailIntlRequest / FromFirm

optional

FromFirm is required if FromFirstName and FromLastName are left blank.

 

For example: <FromFirm></FromFirm>

string

maxLength=32

Restriction enforced via truncation

ExpressMailIntlRequest / FromAddress1

optional

Use this tag for a suite or apartment number only. Either Address1 or Address2 is required.

 

For example: <FromAddress1/>

string

maxLength=32

Restriction enforced via truncation

ExpressMailIntlRequest / FromAddress2

required once

Use this tag for the primary address line.

 

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

string

maxLength=32

Restriction enforced via truncation

ExpressMailIntlRequest / FromUrbanization

optional

Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 009, if area is so designated.

 

For example: <FromUrbanization>URB Caparra Ter</FromUrbanization>

string

maxLength=32

ExpressMailIntlRequest / FromCity

required once

For example: <FromCity>Anytown</FromCity>

string

maxLength=16
minLength=1

ExpressMailIntlRequest / FromState

required once

Use 2-letter USPS abbreviation.

 

For example: <FromState>ST</FromState>

string

length=2

ExpressMailIntlRequest / FromZip5

required once

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

 

For example: <FromZip5>01234</FromZip5>

string

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

ExpressMailIntlRequest / FromZip4

optional

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

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

ExpressMailIntlRequest / FromPhone

required once

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

 

For example: <FromPhone>5555555555</FromPhone>

string

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

ExpressMailIntlRequest / FromCustomsReference

optional

Enter a value for the "Sender's Customs Reference" that will appear on the label. The text entered is any reference number that the sender wishes to use.

 

For example: <FromCustomsReference></FromCustomsReference>

string

maxLength=30

ExpressMailIntlRequest / ToName

optional

Deprecated.  See “ToFirstName” and “ToLastName” tags. 

string

maxLength=36

ExpressMailIntlRequest / ToFirstName

optional

Both ToFirstName and ToLastName are required if ToFirm is left blank.

For example: <ToFirstName>John</ToFirstName> 

string

maxLength=30

ExpressMailIntlRequest / ToLastName

optional

Both ToFirstName and ToLastName are required if ToFirm is left blank.

For example: <ToLastName>Doe</ToLastName> 

string

maxLength=30

ExpressMailIntlRequest / ToFirm

optional

ToFirm is required if ToFirstName and ToLastName are left blank.

For example: <ToFirm></ToFirm> 

string

maxLength=36

ExpressMailIntlRequest / ToAddress1

required once

Three address lines are provided, but only 1 is required. Use as many as needed for complete address.

 

For example: <ToAddress1> Apartado 3068</ToAddress1>

string

maxLength=36
minLength=1

ExpressMailIntlRequest / ToAddress2

optional

Three address lines are provided, but only 1 is required. Use as many as needed for complete address.

 

For example: <ToAddress2></ToAddress2>

string

maxLength=36

ExpressMailIntlRequest / ToAddress3

optional

Three address lines are provided, but only 1 is required. Use as many as needed for complete address.

 

For example: <ToAddress3></ToAddress3>

string

maxLength=36

ExpressMailIntlRequest / ToCity

required once

Recipient's city.

 

For example: <ToCity>PUERTO VALLARTA</ToCity>

string

maxLength=18
minLength=1

ExpressMailIntlRequest / ToProvince

optional

Enter the province for the recipient.

 

For example: <ToProvince>JALISCO</ToProvince>

string

maxLength=9

ExpressMailIntlRequest / ToCountry

required once

The country name entered must match an entry from the USPS-approved International Index of Countries and Localities. See the Index of Countries and Localities. Using a country name not on the list will result in a request failure.

 

For example: <ToCountry>MEXICO</ToCountry>

string

minLength=1

ExpressMailIntlRequest / ToPostalCode

required once

Enter the postal code for the recipient.

 

For example: <ToPostalCode>46807</ToPostalCode>

string

maxLength=9

ExpressMailIntlRequest / ToPOBoxFlag

required once

Indicates whether or not the To Address is a Post Office Box.

 

For example: <ToPOBoxFlag>N</ToPOBoxFlag>

string

enumeration=Y
enumeration=N

ExpressMailIntlRequest / ToPhone

optional

No format checking is done on international phone numbers. Required when <ToPOBoxFlag>Y</ToPOBoxFlag>

 

For example: <ToPhone>011 52 (322) 222-0069</ToPhone>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / ToFax

optional

No format checking is done on international fax numbers.

 

For example: <ToFax>011 52 (322) 222-0074</ToFax>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / ToEmail

optional

Complete valid e-mail address is required if tag is used.

 

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

string

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

Restriction enforced via truncation

ExpressMailIntlRequest / ToCustomsReference

optional

Enter a value for the "Importer's Customs Reference" that will appear on the label. The text entered is any reference number that the recipient wishes to use.

 

For example: <ToCustomsReference>Order #23432</ToCustomsReference>

string

maxLength=28

Restriction enforced via truncation

ExpressMailIntlRequest / 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 below in <AltReturn…> tags. "ABANDON" to dispose of undeliverable package.

 

For example: <NonDeliveryOption>RETURN</NonDeliveryOption>

string

enumeration=RETURN
enumeration=REDIRECT
enumeration=ABANDON

ExpressMailIntlRequest / AltReturnAddress1

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress1></AltReturnAddress1>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / AltReturnAddress2

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress2></AltReturnAddress2>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / AltReturnAddress3

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress3></AltReturnAddress3>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / AltReturnAddress4

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress4></AltReturnAddress4>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / AltReturnAddress5

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress5></AltReturnAddress5>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / AltReturnAddress6

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress6></AltReturnAddress6>

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / AltReturnCountry

optional

Required when <NonDeliveryOption>REDIRECT</NonDeliveryOption> and required to be equal to <ToCountry>

 

For Example: <AltReturnCountry>MEXICO</AltReturnCountry>

string

 

ExpressMailIntlRequest / Container

optional

Use <Container>FLATRATEENV</Container>, <Container>LEGALFLATRATEENV</Container>, or <Container>PADDEDFLATRATEENV</Container> for flat rate envelope variations, and <Container>LEGALFLATRATEBOX</Container> for flat rate boxes.

 

Otherwise, use to specify special containers or container attributes that may affect postage.

 

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

 

For the standard EMI flat rate envelope, gross weight must be 4 pounds or less.

string

default=VARIABLE
enumeration=VARIABLE

enumeration=FLATRATEENV

enumeration=LEGALFLATRATEENV

enumeration=PADDEDFLATRATEENV

enumeration=FLATRATEBOX

enumeration=RECTANGULAR

enumeration=NONRECTANGULAR

ExpressMailIntlRequest / ShippingContents

required once

 

(group)

 

ExpressMailIntlRequest / ShippingContents / ItemDetail

required once repeating up to 30 times

 

(group)

 

ExpressMailIntlRequest / ShippingContents / ItemDetail / Description

required once

Description of the item.

 

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

string

maxLength=56
minLength=1
whiteSpace=collapse

ExpressMailIntlRequest / ShippingContents / ItemDetail / Quantity

required once

Quantity of the item. Integer value required.

 

For example: <Quantity>1</Quantity>

integer

whiteSpace=collapse
minExclusive=0

ExpressMailIntlRequest / ShippingContents / ItemDetail / Value

required once

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.

 

For example: <Value>55.00</Value>

decimal

whiteSpace=collapse
minExclusive=0

ExpressMailIntlRequest / ShippingContents / ItemDetail / NetPounds

required once

Provide the pounds component of the weight of the individual item listed with <Description>.

 

For example: <NetPounds>1</NetPounds>

integer

whiteSpace=collapse

ExpressMailIntlRequest / ShippingContents / ItemDetail / NetOunces

required once

Provide the ounces component of the weight of the individual item listed with <Description>.

 

For example: <NetOunces>5</NetOunces>

integer

 

ExpressMailIntlRequest / ShippingContents / ItemDetail / HSTariffNumber

required once

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

 

For example: <HSTariffNumber>490110</HSTariffNumber>

string

whiteSpace=collapse
maxLength=6
pattern=\d{0,6}

ExpressMailIntlRequest / ShippingContents / ItemDetail / CountryOfOrigin

required once

For commercial items only. 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 and Localities or be "United States". http://pe.usps.gov/text/Imm/immctry.htm – click on the link for “International Country Listings”. Using a country name not on the list will result in a request failure.

 

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

string

 

ExpressMailIntlRequest / InsuredNumber

optional

For backward-compatibility; not validated.

string

 

ExpressMailIntlRequest / InsuredAmount

optional

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

 

For example: <InsuredAmount>100.00</InsuredAmount>

empty

length=0

ExpressMailIntlRequest / Postage

optional

Use this tag for entering a postage amount, if known. If the tag is present, but the value is blank, the postage will be automatically calculated.

 

For example: <Postage></Postage>

empty

length=0

ExpressMailIntlRequest / GrossPounds

required once

Gross pounds and ounces together represent the total package weight, including packing material. For example, a package weighing 3 lbs 8 ounces would have "3" entered here and "8" entered with the <GrossOunces> tag. The Web Tool will check for maximum shipping weight of 70 pounds. Allowable weight may change based on the service used to send package and the destination country.

 

For example: <GrossPounds>4</GrossPounds>

integer

whiteSpace=collapse

ExpressMailIntlRequest / GrossOunces

required once

Enter the ounces component of the total package weight with this tag.

 

For example: <GrossOunces>0</GrossOunces>

integer

 

ExpressMailIntlRequest / ContentType

required once

Specifies the content of the package or envelope.

 

For example: <ContentType>DOCUMENTS</ContentType>

string

enumeration=MERCHANDISE
enumeration=SAMPLE
enumeration=GIFT
enumeration=DOCUMENTS
enumeration=RETURN
enumeration=HUMANITARIAN

enumeration=DANGEROUSGOODS

enumeration=OTHER

ExpressMailIntlRequest / ContentTypeOther

optional

Required when <ContentType>OTHER<ContentType>.

string

maxLength=15
whiteSpace=collapse

ExpressMailIntlRequest / Agreement

required once

Requires a value of Y to print <FromFirstName/> and <FromLastName/> in Signature Box along with Current Date (Central Time USA). Any other value returns an error.

string

enumeration=Y
enumeration=N

ExpressMailIntlRequest / Comments

optional

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

string

maxLength=76

ExpressMailIntlRequest / LicenseNumber

optional

Enter license number, if known or if included in package.

 

For example: <LicenseNumber>LIC-24356879</LicenseNumber>

string

maxLength=24

ExpressMailIntlRequest / CertificateNumber

optional

Enter certificate number, if known or if included in package.

 

For example: <CertificateNumber>CERT-97865342</CertificateNumber>

string

maxLength=24

ExpressMailIntlRequest / InvoiceNumber

optional

Enter invoice number, if known or if included in package.

 

For example: <InvoiceNumber>INV-040903</InvoiceNumber>

string

maxLength=24

ExpressMailIntlRequest / ImageType

required once

For example: <ImageType>PDF</ImageType>

string

enumeration=PDF
enumeration=TIF
enumeration=NONE

ExpressMailIntlRequest / ImageLayout

optional

See section 2.2 Form Output Layout Control.

 

For example: <ImageLayout>TRIMONEPERFILE</ImageLayout>

string

default=ONEPERFILE
enumeration=ONEPERFILE
enumeration=ALLINONEFILE
enumeration=TRIMONEPERFILE
enumeration=TRIMALLINONEFILE

ExpressMailIntlRequest / CustomerRefNo

optional

Written to Postal Manifest Detail record.

 

For example: <CustomerRefNo>Ref #369246</CustomerRefNo>

string

maxLength=30

ExpressMailIntlRequest / POZipCode

optional

ZIP of Post Office where mailed if different from <FromZip5/>. Written to Postal Manifest Detail record. Must be valid ZIP Code.

 

For example: <POZipCode>00962</POZipCode>

string

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

ExpressMailIntlRequest / LabelDate

optional

Date the mail will enter the mail stream. No more than 3 days in the future. Default is day of request.

 

For example: <LabelDate>09/28/2010</LabelDate>

string

whiteSpace=collapse
maxLength=10
pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?

ExpressMailIntlRequest / EMCAAccount

optional

For future use.

empty

 

ExpressMailIntlRequest / EMCAPassword

optional

For future use.

empty

 

ExpressMailIntlRequest / HoldForManifest

optional

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

string

enumeration=Y
enumeration=N

ExpressMailIntlRequest / EELPFC

optional repeating up to 1 times

Exemption and Exclusion Legend or PFC Code. 

 

Please refer to the International Mail Manual for further information - http://pe.usps.gov/text/imm/immc5_007.htm.

 

For example: <EELPFC>30.37a</EELPFC> 

string

whiteSpace=collapse
minLength=0
maxLength=35



 

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

 

ExpressMailIntlRequest / Size

 

optional

Use in conjunction with Revision tag with value of 2 to indicate and trigger new functionality.

 

Defined as follows:

 

REGULAR: Package dimensions are 12’’ or less;

LARGE: Any package dimension is larger than 12’’.

 

For example: <Size>REGULAR</Size> 

string


whiteSpace=collapse
enumeration=LARGE
enumeration=REGULAR

 

ExpressMailIntlRequest / Length

 

optional

Use in conjunction with Revision tag with value of 2 to indicate and trigger new functionality. 

 

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


For example: <Width>5.5</Width> 

decimal

minExclusive=0.0
totalDigits=10  

 

ExpressMailIntlRequest / Width

 

optional

Use in conjunction with Revision tag with value of 2 to indicate and trigger new functionality. 

 

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


For example: <Length>11</Length> 

decimal

minExclusive=0.0
totalDigits=10  

 

ExpressMailIntlRequest / Height

 

optional

Use in conjunction with Revision tag with value of 2 to indicate and trigger new functionality. 

 

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


For example: <Height>11</Height> 

decimal

minExclusive=0.0
totalDigits=10  

 

ExpressMailIntlRequest / Girth

 

optional

Use in conjunction with Revision tag with value of 2 to indicate and trigger new functionality. 

 

Value must be numeric. Units are inches. Required when ExpressMailIntlRequest/Size is LARGE, and ExpressMailIntlRequest/Container is NONRECTANGULAR.

 

For example: <Girth>11</Girth> 

decimal

minExclusive=0.0
totalDigits=10  

ExpressMailIntlRequest / LabelTime

optional

Available if Revision tag >= 2.

 

LabelTime is used in conjunction with LabelDate to determine the Guarantee

string

Format hh:mm

ExpressMailIntRequest / MeterPaymentFlag

optional

Available if Revision tag >= 2.

 

If this flag is set to N and a scheduled delivery date is available for a Kahala country, the estimated delivery days will be displayed instead.  For example, if 01/24/2014 is available for scheduled delivery date and the flag is set to N, 3 – 5 business days to most areas will be displayed.

string

Y or N, default is Y

ExpressMailIntlCertifyRequest

required once

API=ExpressMailIntlCertify

"Certify" signature is for testing and demonstration - does not produce a mailable label  

(alias)

 

 


 

2.1.3     Request Example

<ExpressMailIntlCertifyRequest USERID="XXXXXX" PASSWORD="XXXXXX">

      <Option />

      <Revision>2</Revision>

      <ImageParameters />

      <FromFirstName>John</FromFirstName>

      <FromMiddleInitial>L</FromMiddleInitial>

      <FromLastName>Doe</FromLastName>

      <FromFirm />

      <FromAddress1>Apt 204</FromAddress1>

      <FromAddress2>2711 Ordway St NW</FromAddress2>

      <FromCity>Washington</FromCity>

      <FromState>DC</FromState>

      <FromZip5>20008</FromZip5>

      <FromZip4>5036</FromZip4>

      <FromPhone>3015551212</FromPhone>

      <ToFirstName>Joyce</ToFirstName>

      <ToLastName>Browning</ToLastName>

      <ToFirm></ToFirm>

      <ToAddress1>5th floor</ToAddress1>

      <ToAddress2>2045 Royal Road</ToAddress2>

      <ToAddress3></ToAddress3>

      <ToCity>St Paul</ToCity>

      <ToProvince></ToProvince>

      <ToCountry>France</ToCountry>

      <ToPostalCode>06570</ToPostalCode>

      <ToPOBoxFlag>N</ToPOBoxFlag>

      <ToPhone>4345551212</ToPhone>

      <ToFax>4345559999</ToFax>

      <ToEmail>b@aol.com</ToEmail>

      <NonDeliveryOption>Return</NonDeliveryOption>

      <Container>NONRECTANGULAR</Container>

   <ShippingContents>

      <ItemDetail>

            <Description>Description 1</Description>

            <Quantity>1</Quantity>

            <Value>1.11</Value>

            <NetPounds>1</NetPounds>

            <NetOunces>1</NetOunces>

            <HSTariffNumber>123456</HSTariffNumber>

            <CountryOfOrigin>Brazil</CountryOfOrigin>

      </ItemDetail>

      <ItemDetail>

            <Description>Description 1</Description>

            <Quantity>1</Quantity>

            <Value>1.11</Value>

            <NetPounds>1</NetPounds>

            <NetOunces>1</NetOunces>

            <HSTariffNumber>123456</HSTariffNumber>

            <CountryOfOrigin>Brazil</CountryOfOrigin>

      </ItemDetail>

      <ItemDetail>

            <Description>Description 1</Description>

            <Quantity>1</Quantity>

            <Value>1.11</Value>

            <NetPounds>1</NetPounds>

            <NetOunces>1</NetOunces>

            <HSTariffNumber>123456</HSTariffNumber>

            <CountryOfOrigin>Brazil</CountryOfOrigin>

      </ItemDetail>

      <ItemDetail>

            <Description>Description 1</Description>

            <Quantity>1</Quantity>

            <Value>1.11</Value>

            <NetPounds>1</NetPounds>

            <NetOunces>1</NetOunces>

            <HSTariffNumber>123456</HSTariffNumber>

            <CountryOfOrigin>Brazil</CountryOfOrigin>

      </ItemDetail>

      <ItemDetail>

            <Description>Description 1</Description>

            <Quantity>1</Quantity>

            <Value>1.11</Value>

            <NetPounds>1</NetPounds>

            <NetOunces>1</NetOunces>

            <HSTariffNumber>123456</HSTariffNumber>

            <CountryOfOrigin>Brazil</CountryOfOrigin>

      </ItemDetail>

  </ShippingContents>

      <GrossPounds>17</GrossPounds>

      <GrossOunces>2</GrossOunces>

      <ContentType>Documents</ContentType>

      <Agreement>Y</Agreement>

      <Comments>ExpressMailIntlCertify Comments</Comments>

      <ImageType>TIF</ImageType>

      <ImageLayout>ALLINONEFILE</ImageLayout>

      <POZipCode>20770</POZipCode>

      <LabelDate />

      <HoldForManifest>N</HoldForManifest>

      <Size>LARGE</Size>

      <Length>20.5</Length>

      <Width>7</Width>

      <Height>15</Height>

      <Girth>40</Girth>

</ExpressMailIntlCertifyRequest>

 

 


2.2      Priority Mail Express International Response

 

2.2.1     Response Parameters

Tag Name

Occurs

Description

Type

Validation

ExpressMailIntlResponse

required once

 

(group)

 

ExpressMailIntlResponse / Postage

required once

Postage amount

xs:decimal

 

ExpressMailIntlResponse / TotalValue

required once

Value of all items being shipped

xs:decimal

 

ExpressMailIntlResponse / SDRValue

required once

Special Drawing Right calculated on Insured Amount

xs:decimal

 

ExpressMailIntlResponse / BarcodeNumber

required once

Mail service related barcode, may be empty

xs:string

 

ExpressMailIntlResponse / LabelImage

required once

Encoded images of label (may be empty depending upon layout option selected)

xs:string

 

ExpressMailIntlResponse / Page2Image

required once

Encoded images of label (may be empty depending upon layout option selected)

xs:string

 

ExpressMailIntlResponse / Page3Image

required once

Encoded images of label (may be empty depending upon layout option selected)

xs:string

 

ExpressMailIntlResponse / Page4Image

required once

Encoded images of label (may be empty depending upon layout option selected)

xs:string

 

ExpressMailIntlResponse / Page5Image

required once

Encoded images of label (may be empty depending upon layout option selected)

xs:string

 

ExpressMailIntlResponse / Page6Image

required once

Encoded images of label (may be empty depending upon layout option selected)

xs:string

 

ExpressMailIntlResponse / Prohibitions

required once

List of items prohibited from mailing based on country of destination

xs:string

 

ExpressMailIntlResponse / Restrictions

required once

Restrictions on items being shipped based on country of destination

xs:string

 

ExpressMailIntlResponse / Observations

required once

Additional mailing information based on country of destination

xs:string

 

ExpressMailIntlResponse / Regulations

required once

Additional regulations for shipping to destination country

xs:string

 

ExpressMailIntlResponse / AdditionalRestrictions

required once

Additional restrictions on items being shipped to destination country  

xs:string

 

ExpressMailIntlResponse / Notes

required once

Express Mail International Notes

xs:string

 

ExpressMailIntlResponse / InsuranceFee

optional

Insurance Fee

decimal

minExclusive=0.0

maxInclusive=5000

ExpressMailIntlResponse / GuaranteeAvailability

optional

If the Revision tag >= 2 in the request, the MeterPaymentFlag is Y or empty, and the country is a Kahala country, the GuaranteeAvailability tag will display the estimated scheduled delivery date.  If not, the tag will contain the estimated scheduled delivery days.

string

If an estimated scheduled delivery date is available, the format will be

MM/DD/YYYY

 

, e.g,

 

01/29/2014. 

 

If an estimated scheduled delivery date is not available, the formate will be a string, e.g.,

 

3 - 5 business days to many major markets

 

ExpressMailIntlCertifyResponse

required once

 

(alias)

 

 




2.2.5     Response Example

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

<ExpressMailIntlCertifyResponse>

  <Postage>102.90</Postage>

  <TotalValue>5.55</TotalValue>

  <SDRValue />

  <BarcodeNumber>EC549998824US</BarcodeNumber>

  <LabelImage>

    SUkqAAgAAAASAP4ABAABAAAAAAAAA <!-- Data Truncated -->

  </LabelImage>

  <Page2Image />

  <Page3Image />

  <Page4Image />

  <Page5Image />

  <Page6Image />

  <Prohibitions>

    Arms, ammunition. Cigarett <!-- Data Truncated -->

  </Prohibitions>

  <Restrictions>

    Bees, honey, and beeswax m <!-- Data Truncated -->

  </Restrictions>

  <Observations>

    1. A parcel may be address <!-- Data Truncated -->

  </Observations>

  <Regulations>

    Country Code: FR Reciprocal <!-- Data Truncated -->

  </Regulations>

  <AdditionalRestrictions>No Additional Restrictions Data  found.</AdditionalRestrictions>

  <GuaranteeAvailability>01/29/2014</GuaranteeAvailability>

</ExpressMailIntlCertifyResponse>

 


3     Priority Mail International API

3.1      Priority Mail International Request

The table below presents the XML input tags for generating Live requests and 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.

3.1.1     API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PriorityMailIntl

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PriorityMailIntlCertify

&XML=(see below)


 

 

3.1.2     Request Parameters

Tag Name

Occurs

Description

Type

Validation

PriorityMailIntlRequest

required once

Produces a Priority Mail International label with customs declaraction  

(group)

 

PriorityMailIntlRequest / @USERID

required

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

NMTOKEN

 

PriorityMailIntlRequest / @PASSWORD

optional

For backward compatibility; not validated. 

NMTOKEN

 

PriorityMailIntlRequest / Option

optional

For future use.  

empty

 

PriorityMailIntlRequest / Revision

required

Use of value 2 required as of January 2011.

 

For example: <Revision>2</Revision>

string

 

PriorityMailIntlRequest / ImageParameters

optional

Groups alternate image options.

(group)

 

PriorityMailIntlRequest / ImageParameters / ImageParameter

Optional, repeating up to 3 times

Returns alternate label image.  Only alternate 4’’x6’’ size label image may be requested at this time.  

For example: <ImageParameter>4BY6LABEL</ImageParameter> 

empty

Enumeration=4BY6LABEL

PriorityMailIntlRequest / FromFirstName

optional

Both FromFirstName and FromLastName are required if FromFirmName is left blank. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name.

 

For example: <FromFirstName>John</FromFirstName>

string

maxLength=30
minLength=1
Restriction enforced via truncation  

PriorityMailIntlRequest / FromMiddleInitial

optional

Middle Initial. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name.

 

For example: <FromMiddleInitial>L</FromMiddleInitial>  

string

maxLength=1
Restriction enforced via truncation  

PriorityMailIntlRequest / FromLastName

optional

Both FromFirstName and FromLastName are required if FromFirmName is left blank.  Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name.

 

For example: <FromLastName>Doe</FromLastName>  

string

maxLength=30
minLength=1
Restriction enforced via truncation  

PriorityMailIntlRequest / FromFirm

optional

FromFirm is required if FromFirstName and FromLastName are left blank.

 

For example: <FromFirm></FromFirm>  

string

maxLength=32
Restriction enforced via truncation  

PriorityMailIntlRequest / FromAddress1

optional

Use this tag for a suite or apartment number only. Either Address1 or Address2 is required.

 

For example: <FromAddress1/>  

string

maxLength=32
Restriction enforced via truncation  

PriorityMailIntlRequest / FromAddress2

required once

Use this tag for the primary address line.

 

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

string

maxLength=32
minLength=1
whiteSpace=collapse
Restriction enforced via truncation  

PriorityMailIntlRequest / FromUrbanization

optional

Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 009, if area is so designated.

 

For example: <FromUrbanization>URB Caparra Ter</FromUrbanization>  

string

maxLength=32  

PriorityMailIntlRequest / FromCity

required once

For example: <FromCity>Anytown</FromCity>  

string

maxLength=16
minLength=1  

PriorityMailIntlRequest / FromState

required once

Use 2-letter USPS abbreviation.

 

For example: <FromState>ST</FromState>  

string

length=2  

PriorityMailIntlRequest / FromZip5

required once

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

 

For example: <FromZip5>01234</FromZip5>  

string

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

PriorityMailIntlRequest / FromZip4

optional

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

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

PriorityMailIntlRequest / FromPhone

required once

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

 

For example: <FromPhone>5555555555</FromPhone>  

string

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

PriorityMailIntlRequest / FromCustomsReference

optional

Enter a value for the "Sender's Customs Reference" that will appear on the label. The text entered is any reference number that the sender wishes to use.

 

For example: <FromCustomsReference></FromCustomsReference>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30  

PriorityMailIntlRequest / ToName

optional

Deprecated.  See “ToFirstName” and “ToLastName” tags. 

string

maxLength=36

PriorityMailIntlRequest / ToFirstName

optional

Both ToFirstName and ToLastName are required if ToFirm is left blank.

For example: <ToFirstName>John</ToFirstName> 

string

maxLength=30

PriorityMailIntlRequest / ToLastName

optional

Both ToFirstName and ToLastName are required if ToFirm is left blank.

For example: <ToLastName>Doe</ToLastName> 

string

maxLength=30

PriorityMailIntlRequest / ToFirm

optional

ToFirm is required if ToFirstName and ToLastName are left blank.

For example: <ToFirm></ToFirm> 

string

maxLength=36

PriorityMailIntlRequest / ToAddress1

required once

Three address lines are provided, but only 1 is required. Use as many as needed for complete address.

 

For example: <ToAddress1> Apartado 3068</ToAddress1>  

string

maxLength=36
minLength=1  

PriorityMailIntlRequest / ToAddress2

optional

Three address lines are provided, but only 1 is required. Use as many as needed for complete address.

 

For example: <ToAddress2></ToAddress2>  

string

maxLength=36  

PriorityMailIntlRequest / ToAddress3

optional

Three address lines are provided, but only 1 is required. Use as many as needed for complete address.

 

For example: <ToAddress3></ToAddress3>  

string

maxLength=36  

PriorityMailIntlRequest / ToCity

required once

Recipient's city.

 

For example: <ToCity>PUERTO VALLARTA</ToCity>  

string

maxLength=18
minLength=1  

PriorityMailIntlRequest / ToProvince

optional

Enter the province for the recipient.

 

For example: <ToProvince>JALISCO</ToProvince>  

string

maxLength=9  

PriorityMailIntlRequest / ToCountry

required once

The country name entered must match an entry from the USPS-approved International Index of Countries and Localities. (http://pe.usps.gov/text/Imm/Immctry.htm - click on the link for "International Country Listings.") Using a country name not on the list will result in a request failure.

 

For example: <ToCountry>MEXICO</ToCountry>  

string

minLength=1  

PriorityMailIntlRequest / ToPostalCode

required once

Enter the postal code for the recipient.

 

For example: <ToPostalCode>46807</ToPostalCode>  

string

maxLength=9  

PriorityMailIntlRequest / ToPOBoxFlag

required once

Indicates whether or not the To Address is a Post Office Box.

 

For example: <ToPOBoxFlag>N</ToPOBoxFlag>  

string

enumeration=Y
enumeration=N  

PriorityMailIntlRequest / ToPhone

optional

No format checking is done on international phone numbers. Required when <ToPOBoxFlag>Y</ToPOBoxFlag>

 

For example: <ToPhone>011 52 (322) 222-0069</ToPhone>  

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / ToFax

optional

No format checking is done on international fax numbers.

 

For example: <ToFax>011 52 (322) 222-0074</ToFax>  

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / ToEmail

optional

Complete valid e-mail address is required if tag is used.

 

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

string

maxLength=30
whiteSpace=collapse
pattern=([\w\-\.]+)@(([\w-]+\.))+[a-zA-Z]{2,4}
Restriction enforced via truncation  

PriorityMailIntlRequest / ToCustomsReference

optional

Enter a value for the "Recipient's Reference" that will appear on the label. The text entered is any reference number that the recipient wishes to use.

 

For example: <ToReference>Order #23432</ToReference>  

string

maxLength=28
Restriction enforced via truncation  

PriorityMailIntlRequest / 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 below in <AltReturn…> tags. "ABANDON" to dispose of undeliverable package.

 

For example: <NonDeliveryOption>RETURN</NonDeliveryOption>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

default=ABANDON
enumeration=RETURN
enumeration=REDIRECT
enumeration=ABANDON  

PriorityMailIntlRequest / AltReturnAddress1

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress1></AltReturnAddress1>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / AltReturnAddress2

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress2></AltReturnAddress2>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / AltReturnAddress3

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress3></AltReturnAddress3>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / AltReturnAddress4

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress4></AltReturnAddress4>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / AltReturnAddress5

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress5></AltReturnAddress5>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / AltReturnAddress6

optional

Valid only with the "REDIRECT" value with the <NonDeliveryOption> tag. Six address lines are provided but only one is required. Use as many as needed for complete address.

 

For example: <AltReturnAddress6></AltReturnAddress6>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30
Restriction enforced via truncation  

PriorityMailIntlRequest / AltReturnCountry

optional

Required when <NonDeliveryOption>REDIRECT</NonDeliveryOption> and required to be equal to <ToCountry>

 

For Example: <AltReturnCountry>MEXICO</AltReturnCountry>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

 

PriorityMailIntlRequest / Container

optional

Use <Container>MDFLATRATEBOX</Container> or <Container>LGFLATRATEBOX</Container> or <Container>SMFLATRATEBOX</Container> or <Container>LGVIDEOBOX</Container> or <Container>DVDBOX</Container> for flat rate boxes,

 

<Container>FLATRATEENV</Container> or <Container>LEGALFLATRATEENV</Container> or <Container>PADDEDFLATRATEENV</Container> or <Container>WINDOWFLATRATEENV</Container> or <Container>SMFLATRATEENV</Container> or <Container>GIFTCARDFLATRATEENV</Container> for flat rate envelopes. 

 

Otherwise, use to specify special containers or container attributes that may affect postage.

 

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

 

For the flat rate envelope and small flat rate box variations, gross weight must be 4 pounds or less and total value must be at most $400.  

string

default=VARIABLE
enumeration=VARIABLE

enumeration=RECTANGULAR

enumeration=NONRECTANGULAR
enumeration=LGFLATRATEBOX
enumeration=MDFLATRATEBOX

enumeration=SMFLATRATEBOX
enumeration=FLATRATEBOX
enumeration=LGVIDEOBOX

enumeration=DVDBOX enumeration=FLATRATEENV

enumeration=LEGALFLATRATEENV

enumeration=PADDEDFLATRATEENV

enumeration=WINDOWFLATRATEENV

enumeration=SMFLATRATEENV

enumeration=GIFTCARDFLATRATEENV

 

PriorityMailIntlRequest / ShippingContents

required once

 

(group)

 

PriorityMailIntlRequest / ShippingContents / ItemDetail

required once repeating up to 30 times

When <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DVDBOX, LGVIDEOBOX) variation, maxOccurs=”5”; that is, a maximum of five <ItemDetail/> tags is permitted.  

(group)

 

PriorityMailIntlRequest / ShippingContents / ItemDetail / Description

required once

Description of the item.

 

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

string

maxLength=56
minLength=1
whiteSpace=collapse  

PriorityMailIntlRequest / ShippingContents / ItemDetail / Quantity

required once

Quantity of the item. Integer value required.

 

For example: <Quantity>1</Quantity>  

integer

whiteSpace=collapse
minExclusive=0  

PriorityMailIntlRequest / ShippingContents / ItemDetail / Value

required once

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.

 

For example: <Value>55.00</Value>  

decimal

whiteSpace=collapse
minExclusive=0  

PriorityMailIntlRequest / ShippingContents / ItemDetail / NetPounds

required once

Provide the pounds component of the weight of the individual item listed with <Description>.

 

For example: <NetPounds>1</NetPounds>  

integer

default=0
whiteSpace=collapse  

PriorityMailIntlRequest / ShippingContents / ItemDetail / NetOunces

required once

Provide the ounces component of the weight of the individual item listed with <Description>.

 

For example: <NetOunces>5</NetOunces>  

decimal

default=0.0
whiteSpace=collapse  

PriorityMailIntlRequest / ShippingContents / ItemDetail / HSTariffNumber

required once

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

 

For example: <HSTariffNumber>490110</HSTariffNumber>  

String

whiteSpace=collapse
maxLength=6
pattern=\d{0,6}  

PriorityMailIntlRequest / ShippingContents / ItemDetail / CountryOfOrigin

required once

For commercial items only. 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 and Localities or be "United States". (http://pe.usps.gov/text/Imm/Immctry.htm - click on the link for "International Country Listings.") Using a country name not on the list will result in a request failure.

 

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

String

 

PriorityMailIntlRequest / Insured

optional

Restricted use: authorized users may indicate with a value of Y that the item is insured for purposes of obtaining a barcode number from the insured range. All other users must specify N or omit.  

string

default=N
enumeration=Y
enumeration=N  

PriorityMailIntlRequest / InsuredNumber

optional

For backward-compatibility; not validated.

string

 

PriorityMailIntlRequest / InsuredAmount

optional

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

 

For example: <InsuredAmount>100.00</InsuredAmount>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string
decimal

length=0  

PriorityMailIntlRequest / Postage

optional

Use this tag for entering a postage amount, if known. If the tag is present, but the value is blank, the postage will be automatically calculated.

 

For example: <Postage></Postage>  

string
decimal

length=0  

PriorityMailIntlRequest / GrossPounds

required once

Gross pounds and ounces together represent the total package weight, including packing material. For example, a package weighing 3 lbs 8 ounces would have "3" entered here and "8" entered with the <GrossOunces> tag. The Web Tool will check for maximum shipping weight of 70 pounds. Allowable weight may change based on the service used to send package and the destination country.

 

For example: <GrossPounds>4</GrossPounds>  

integer

whiteSpace=collapse  

PriorityMailIntlRequest / GrossOunces

required once

Enter the ounces component of the total package weight with this tag.

 

For example: <GrossOunces>0</GrossOunces>  

decimal

whiteSpace=collapse  

PriorityMailIntlRequest / ContentType

required once

Specifies the content of the package or envelope.

 

For example: <ContentType>DOCUMENTS</ContentType>

 

Note: when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation, RETURN is not a valid option. 

string

enumeration=MERCHANDISE
enumeration=SAMPLE
enumeration=GIFT
enumeration=DOCUMENTS
enumeration=RETURN

enumeration=HUMANITARIAN

enumeration=DANGEROUSGOODS

enumeration=OTHER  

PriorityMailIntlRequest / ContentTypeOther

optional

Required when <ContentType>OTHER<ContentType>.  Maximum length enforced via truncation 

string

maxLength=15
whiteSpace=collapse  

PriorityMailIntlRequest / Agreement

required once

Requires a value of Y to print <FromFirstName/> and <FromLastName/> in Signature Box along with Current Date (Central Time USA). Any other value returns an error.  

string

enumeration=Y
enumeration=N  

PriorityMailIntlRequest / Comments

optional

Enter any comments.

 

For example: <Comments></Comments>

 

Note: ignored when <Container> specified is a flat rate envelope.

string

maxLength=76  

PriorityMailIntlRequest / LicenseNumber

optional

Enter license number, if known or if included in package.

 

For example: <LicenseNumber>LIC-24356879</LicenseNumber>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=24  

PriorityMailIntlRequest / CertificateNumber

optional

Enter certificate number, if known or if included in package.

 

For example: <CertificateNumber>CERT-97865342</CertificateNumber>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=24  

PriorityMailIntlRequest / InvoiceNumber

optional

Enter invoice number, if known or if included in package.

 

For example: <InvoiceNumber>INV-040903</InvoiceNumber>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=24  

PriorityMailIntlRequest / ImageType

required once

For example: <ImageType>PDF</ImageType>  

string

enumeration=PDF
enumeration=TIF
enumeration=NONE  

PriorityMailIntlRequest / ImageLayout

optional

See section 2.2 Form Output Layout Control.

 

For example: <ImageLayout>TRIMONEPERFILE</ImageLayout>  

string

default=ONEPERFILE
enumeration=ONEPERFILE
enumeration=ALLINONEFILE
enumeration=TRIMONEPERFILE
enumeration=TRIMALLINONEFILE  

PriorityMailIntlRequest / CustomerRefNo

optional

Written to Postal Manifest Detail record.

 

For example: <CustomerRefNo>Ref #369246</CustomerRefNo>

 

Note: ignored when <Container> specified is a flat rate envelope or small flat rate box (SMFLATRATEBOX, DXDBOX, LGVIDEOBOX) variation.

string

maxLength=30  

PriorityMailIntlRequest / POZipCode

optional

ZIP of Post Office where mailed if different from <FromZip5/>. Written to Postal Manifest Detail record. Must be valid ZIP Code.

 

For example: <POZipCode>00962</POZipCode>  

string

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

PriorityMailIntlRequest / LabelDate

optional

Date the mail will enter the mail stream. No more than 3 days in the future. Default is day of request.

 

For example: <LabelDate>09/28/2010</LabelDate>  

string

whiteSpace=collapse
maxLength=10
pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?  

PriorityMailIntlRequest / HoldForManifest

optional

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

string

enumeration=Y
enumeration=N

PriorityMailIntlRequest / EELPFC

optional

Exemption and Exclusion Legend or PFC Code.  Use in conjunction with Revision tag with value of 1 to indicate and trigger new functionality.

 

Please refer to the International Mail Manual for further information - http://pe.usps.gov/text/imm/immc5_007.htm.

 

To activate check boxes use ”30.37a” or “30.37h”.

 

For example: <EELPFC>30.37a</EELPFC> 

string

whiteSpace=collapse
minLength=0
maxLength=35



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

 

PriorityMailIntlRequest / Size

 

optional

Use in conjunction with Revision tag with value of 2 to indicate and trigger new functionality.

 

Defined as follows:

 

REGULAR: Package dimensions are 12’’ or less;

LARGE: Any package dimension is larger than 12’’.

 

For example: <Size>REGULAR</Size> 

string


whiteSpace=collapse
enumeration=LARGE
enumeration=REGULAR

 

PriorityMailIntlRequest / Length

 

optional

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


For example: <Width>5.5</Width> 

decimal

minExclusive=0.0
totalDigits=10  

 

PriorityMailIntlRequest / Width

 

optional

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


For example: <Length>11</Length> 

decimal

minExclusive=0.0
totalDigits=10  

 

PriorityMailIntlRequest / Height

 

optional

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


For example: <Height>11</Height> 

decimal

minExclusive=0.0
totalDigits=10  

 

PriorityMailIntlRequest / Girth

 

optional

Value must be numeric. Units are inches. Required when PriorityMailIntlRequest/Size is LARGE, and PriorityMailIntlRequest/Container is NONRECTANGULAR.

 

For example: <Girth>11</Girth> 

decimal

minExclusive=0.0
totalDigits=10  

PriorityMailIntlRequest /

ExtraServices

optional

Groups extra services elements

(group)

 

PriorityMailIntlRequest /

ExtraServices / ExtraService

optional, repeating up to 1 times

Use to specify extra services.  Currently available extra service is electronic USPS Delivery Confirmation International.

 

Extra Service Name

ServiceID

e-USPS Delivery Confirmation International

9

 

Electronic USPS Delivery Confirmation International is only available when <Container> specified is a flat rate envelope (FLATRATEENV, LEGALFLATRATEENV, PADDEDFLATRATEENV, WINDOWFLATRATEENV, SMFLATRATEENV) or small flat rate box (SMFLATRATEBOX, DVDBOX, LGVIDEOBOX) variation,

 

For example: <ExtraService>9</ExtraService>

string

whiteSpace=collapse

enumeration=9

PriorityMailIntlCertifyRequest

required once

API=PriorityMailIntlCertify

"Certify" signature is for testing and demonstration - does not produce a mailable label  

(alias)

 

 


 

3.1.3     Request Example

<PriorityMailIntlCertifyRequest USERID="xxx">

            <Option/>

             <Revision>2</Revision>

            <ImageParameters/>

            <FromFirstName>John</FromFirstName>

            <FromMiddleInitial>L</FromMiddleInitial>

            <FromLastName>Doe</FromLastName>

            <FromFirm>USPS</FromFirm>

            <FromAddress1>Suite 10000</FromAddress1>

            <FromAddress2>475 Lenfant</FromAddress2>

            <FromCity>Washington</FromCity>

            <FromState>DC</FromState>

            <FromZip5>20260</FromZip5>

            <FromPhone>2025551212</FromPhone>

            <ToFirstName>Joyce</ToFirstName>

            <ToLastName>Browning</ToLastName>

            <ToFirm>XYZ Corp.</ToFirm>

            <ToAddress1>5th Floor</ToAddress1>

            <ToAddress2>Frankfurter Allee 1</ToAddress2>

            <ToAddress3></ToAddress3>

            <ToCity>Munich</ToCity>

            <ToProvince></ToProvince>

            <ToCountry>Germany</ToCountry>

            <ToPostalCode>83497</ToPostalCode>

            <ToPOBoxFlag>N</ToPOBoxFlag>

            <ToPhone>5155551212</ToPhone>

            <ToFax>8884865188</ToFax>

            <ToEmail>b@aol.com</ToEmail>

            <NonDeliveryOption>Return</NonDeliveryOption>

            <Container>VARIABLE</Container>

            <ShippingContents>

                        <ItemDetail>

                                    <Description>Description 1</Description>

                                    <Quantity>1</Quantity>

                                    <Value>1.11</Value>

                                    <NetPounds>1</NetPounds>

                                    <NetOunces>1</NetOunces>

                                    <HSTariffNumber>123456</HSTariffNumber>

                                    <CountryOfOrigin>Brazil</CountryOfOrigin>

                        </ItemDetail>

                        <ItemDetail>