International Label APIs

 

 

USPS Web Tools™

Application Programming Interface

User’s Guide

Document Version 5.5 (4/23/2016)

 

 

 

 

 

 

 

 

 

 


 

 


Table of Contents

Introduction to Web Tools. 3

Before you get started: 3

Priority Mail Express International Label API. 4

Overview.. 4

API Signature. 4

Request Descriptions. 4

Sample Requests. 16

Response Descriptions. 18

Sample Response. 20

Label Sample (4X6) 21

Error Responses. 22

Priority Mail International Label API. 23

Overview.. 23

API Signature. 23

Request Descriptions. 23

Sample Requests. 36

Response Descriptions. 39

Sample Response. 41

Label Sample (4X6) 42

Error Responses. 43

First Class Mail International Label API. 44

Overview.. 44

API Signature. 44

Request Descriptions. 44

Sample Request 53

Response Descriptions. 55

Sample Response. 56

Label Sample (4X6) 57

Error Responses. 58

 


Introduction to Web Tools

This document contains a Reference Guide to the international label APIs, Priority Mail Express International, Priority Mail International and First Class Mail International. 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:

 

<Pounds>2</Pounds>

 

In this instance, you will replace “2” with the weight in pounds for the 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 APIs require extra permissions; contact the Internet Customer Care Center (uspstechnicalsupport@mailps.custhelp.com) to request access. Indicate “Label API Access” in the subject line and explain in the body of the email:

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

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


 

Priority Mail Express International Label API

Overview

The Priority Mail Express International Label API lets customers generate Priority Mail Express International labels given the weight and dimensions of the item. 

API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=ExpressMailIntl

&XML=(see Tag Descriptions below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=ExpressMailIntlCertify

&XML=(see Tag Descriptions below)

 

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

Request Descriptions

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

 

·      4X6LABEL (4X6 on a full page 8.5/11” background)

·      4X6LABELL (Landscape – true size 4X6; image rotated, not on an 8.5 x 11 background page)

·      4X6LABELP (Portrait – true size 4X6, not on an 8.5 x 11 background page)

 

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

string

Enumeration=

4X6LABEL

4X6LABELL

4X6LABELP

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

Restriction enforced via truncation

ExpressMailIntlRequest / ToLastName

optional

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

For example: <ToLastName>Doe</ToLastName> 

string

maxLength=30

Restriction enforced via truncation

ExpressMailIntlRequest / ToFirm

optional

ToFirm is required if ToFirstName and ToLastName are left blank.

For example: <ToFirm></ToFirm> 

string

maxLength=36

Restriction enforced via truncation

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

Restriction enforced via truncation

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

Restriction enforced via truncation

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

Restriction enforced via truncation

ExpressMailIntlRequest / ToCity

required once

Recipient's city.

 

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

string

maxLength=18
minLength=1

Restriction enforced via truncation

ExpressMailIntlRequest / ToProvince

optional

Enter the province for the recipient.

 

For example: <ToProvince>JALISCO</ToProvince>

string

maxLength=9

Restriction enforced via truncation

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

Restriction enforced via truncation

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 to specify special containers or container attributes that may affect postage.

 

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

string

default=VARIABLE
enumeration=

·      VARIABLE

·      FLATRATEENV

·      LEGALFLATRATEENV

·      PADDEDFLATRATEENV

·      RECTANGULAR

·      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

Restriction enforced via truncation

ExpressMailIntlRequest / ShippingContents / ItemDetail / Quantity

required once

Quantity of the item. Integer value required.

 

For example: <Quantity>1</Quantity>

integer

whiteSpace=collapse
minExclusive=1

maxInclusive=999

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>

decimal

Default=0.0

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>490110490110</HSTariffNumber>

string

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

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

 

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

string

 

ExpressMailIntlRequest / InsuredNumber

optional

For backward-compatibility; not validated.

string

minOccurs=0

ExpressMailIntlRequest / InsuredAmount

optional

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

 

For example: <InsuredAmount>100.00</InsuredAmount>

string

minOccurs=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>  or <Postage>10.50</Postage>

string

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

default=0

ExpressMailIntlRequest / GrossOunces

required once

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

 

For example: <GrossOunces>0</GrossOunces>

integer

default=0

ExpressMailIntlRequest / ContentType

required once

Specifies the content of the package or envelope.

 

For example: <ContentType>DOCUMENTS</ContentType>

 

Note: enumerations are case sensitive

 

“NonnegotiableDocument” and “Documents” both signify mailable non-negotiable documents and are insured automatically for up to $100, though Insurance will not be returned as an extra service. Additional Insurance cannot be purchased. 

 

Any non-document ContentType values are insured automatically for up to $200 and Insurance will be returned as an explicit extra service in the response. Additional Insurance can be purchased for values $200 and greater.

string

enumerations=

·   MERCHANDISE

·   SAMPLE

·   GIFT

·   DOCUMENTS

·   RETURN

·   HUMANITARIAN

·   DANGEROUSGOODS

·   CrematedRemains

·   NonnegotiableDocument

·   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

Restriction enforced via truncation

ExpressMailIntlRequest / LicenseNumber

optional

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

 

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

string

maxLength=24

Restriction enforced via truncation

ExpressMailIntlRequest / CertificateNumber

optional

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

 

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

string

maxLength=24

Restriction enforced via truncation

ExpressMailIntlRequest / InvoiceNumber

optional

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

 

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

string

maxLength=24

Restriction enforced via truncation

ExpressMailIntlRequest / ImageType

required once

For example: <ImageType>PDF</ImageType>

string

enumeration=PDF
enumeration=TIF
enumeration=NONE

ExpressMailIntlRequest / ImageLayout

optional

Controls how the multipage form is returned in the response tags. "ONEPERFILE" returns one page per response tag while “ALLINONEFILE” returns all pages in a single response tag.

 

For example:

<ImageLayout>ONEPERFILE<ImageLayout> 

string

default=ONEPERFILE

enumerations=

ONEPERFILE
ALLINONEFILE  

ExpressMailIntlRequest / CustomerRefNo

optional

Written to Postal Manifest Detail record.

 

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

string

maxLength=30

Restriction enforced via truncation

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

 

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.

 

For example: <CommercialPrice>False</CommercialPrice>

string

default=false

enumeration=TRUE

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

string

minOccurs=0  

 

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> 

string

minOccurs=0  

 

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> 

string

minOccurs=0  

 

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> 

string

minOccurs=0  

ExpressMailIntlRequest / LabelTime

optional

Available if Revision tag >= 2.

 

LabelTime is used in conjunction with LabelDate to determine the Guarantee

string

minOccurs=0

ExpressMailIntRequest / MeterPaymentFlag

optional

Available if Revision tag >= 2.

 

Set to Y if the Scheduled Delivery Date should appear on the label, N otherwise.

 

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

default=Y

enumeration=Y

enumeration=N

ExpressMailIntRequest /MeterData

optional

Meter Data grouping.

(group)

 

ExpressMailIntRequest /MeterData/ MeterVendorID

optional

Meter Vendor ID, which is the 2 digit number USPS assigned vendor ID.

string

minLength value="0"

maxLength value="2"

 

ExpressMailIntRequest /MeterData/ MeterSerialNumber

optional

Serial number of meter used for postage.

string

minLength value="0"

maxLength value="20"

 

ExpressMailIntRequest /MeterData/ MeterModelID

optional

Two digit model number of the Meter

 

For example: PC-Postage models are 1 numeric followed by 1 alpha.

<MeterModelID>7a</MeterModelID>

string

minLength value="0"

maxLength value="15"

 

ExpressMailIntRequest /MeterData/ RateCategory

optional

Four digit value denotes Product / Rate Category (As defined by the IBI data dictionary)

 

string

minLength value="0"

maxLength value="4"

               

ExpressMailIntRequest/ MeterData/ IndiciumCreationRecordDate

optional

Date IBI was created

Example: 12/19/2016

 

This tag is mostly used by PC Postage, metered and IMI PC Compliant customers

string

pattern value="\d{1,2}/\d{1,2}/\d{4}|"

ExpressMailIntRequest /MeterData/IBI

optional

Information-Based Indicia (IBI)- Refers to a secure postage evidencing standard used by the United States Postal Service (USPS) to indicate electronic postage payment.

string

minLength value="0"

maxLength value="150"

               

ExpressMailIntlCertifyRequest

required once

API=ExpressMailIntlCertify

"Certify" signature is for testing and demonstration - does not produce a label that can be mailed.  

(alias)

 

 

Sample Requests

All requests should hit the https://secure.shippingapis.com/ShippingAPI.dll end point with the API=ExpressMailIntl or ExpressMailIntlCertify and XML=<the sample XML request below> key value pairs using either a HTTP POST or a HTTP GET.

 

Request:

ExpressMailIntlCertifyRequest USERID=xxxxxxx>

<Option></Option>

<Revision>2</Revision>

<ImageParameters>

<ImageParameter>4by6label</ImageParameter>

</ImageParameters>

<FromFirstName>Johnathon</FromFirstName>

<FromMiddleInitial>L</FromMiddleInitial>

<FromLastName>Seagull</FromLastName>

<FromFirm>The Firm Mattress Co.</FromFirm>

<FromAddress1>Some Addrr1</FromAddress1>

<FromAddress2>7 North Wilke-Barre Blvd</FromAddress2>

<FromUrbanization>The URB</FromUrbanization>

<FromCity>Wilkes-Barre</FromCity>

<FromState>PA</FromState>

<FromZip5>18702</FromZip5>

<FromZip4>2222</FromZip4>

<FromPhone>5555555555</FromPhone>

<FromCustomsReference>My From Customs REF</FromCustomsReference>

<ToName></ToName>

<ToFirstName>Ms. C. P.</ToFirstName>

<ToLastName>Apple</ToLastName>

<ToFirm>The To FIRM</ToFirm>

<ToAddress1> Apartado 3068</ToAddress1>

<ToAddress2>The Addr2</ToAddress2>

<ToAddress3>The Addr3</ToAddress3>

<ToCity>Golden Rock</ToCity>

<ToProvince>TheProv</ToProvince>

<ToCountry>Mexico</ToCountry>

<ToPostalCode>2046</ToPostalCode>

<ToPOBoxFlag>N</ToPOBoxFlag>

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

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

<ToEmail>cpapple@email.com</ToEmail>

<ToCustomsReference>The Imp Ref#</ToCustomsReference>

<NonDeliveryOption>RETURN</NonDeliveryOption>

<Container>VARIABLE</Container>

<ShippingContents>

<ItemDetail>

<Description>Policy guidelines document</Description>

<Quantity>1</Quantity>

<Value>55.00</Value>

<NetPounds>1</NetPounds>

<NetOunces>5</NetOunces>

<HSTariffNumber>490110490110</HSTariffNumber>

<CountryOfOrigin>United States</CountryOfOrigin>

</ItemDetail><ItemDetail>

<Description>Policy guidelines document</Description>

<Quantity>1</Quantity>

<Value>55.00</Value>

<NetPounds>0</NetPounds>

<NetOunces>5</NetOunces>

<HSTariffNumber>490110490110</HSTariffNumber>

<CountryOfOrigin>United States</CountryOfOrigin>

</ItemDetail></ShippingContents>

<InsuredNumber>V-12324589765</InsuredNumber>

<InsuredAmount>100.00</InsuredAmount>

<GrossPounds>4</GrossPounds>

<GrossOunces>0</GrossOunces>

<ContentType>DOCUMENTS</ContentType>

<ContentTypeOther></ContentTypeOther>

<Agreement>Y</Agreement>

<Comments>NO Comment!</Comments>

<LicenseNumber>LIC-24356879</LicenseNumber>

<CertificateNumber>CERT-97865342</CertificateNumber>

<InvoiceNumber>INV-040903</InvoiceNumber>

<ImageType>TIF</ImageType>

<ImageLayout>TRIMALLINONEFILE</ImageLayout>

<CustomerRefNo>Cust Ref #369246</CustomerRefNo>

<POZipCode>00962</POZipCode>

<LabelDate></LabelDate>

<HoldForManifest>N</HoldForManifest>

<EELPFC>802.11B</EELPFC> 

<Size>LARGE</Size>

<Length>20.5</Length>

<Width>5.9</Width>

<Height>9.5</Height>

<Girth>6.25</Girth>

<LabelTime>14:24:13</LabelTime>

<MeterPaymentFlag>N</MeterPaymentFlag>

</ExpressMailIntlCertifyRequest>


 

 

Response Descriptions

Tag Name

Occurs

Description

Type

Validation

ExpressMailIntlResponse

required once

 

(group)

 

ExpressMailIntlResponse / Postage

required once

Postage amount

decimal

 

ExpressMailIntlResponse / TotalValue

required once

Value of all items being shipped

decimal

 

ExpressMailIntlResponse / SDRValue

required once

Special Drawing Right calculated on Insured Amount

decimal

 

ExpressMailIntlResponse / BarcodeNumber

required once

Mail service related barcode, may be empty

string

 

ExpressMailIntlResponse / LabelImage

required once

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

base64Binary

 

ExpressMailIntlResponse / Page2Image

required once

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

base64Binary

 

ExpressMailIntlResponse / Page3Image

required once

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

base64Binary

 

ExpressMailIntlResponse / Page4Image

required once

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

base64Binary

 

ExpressMailIntlResponse / Page5Image

required once

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

base64Binary

 

ExpressMailIntlResponse / Page6Image

required once

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

base64Binary

 

ExpressMailIntlResponse / Prohibitions

required once

List of items prohibited from mailing based on country of destination

string

 

ExpressMailIntlResponse / Restrictions

required once

Restrictions on items being shipped based on country of destination

string

 

ExpressMailIntlResponse / Observations

required once

Additional mailing information based on country of destination

string

 

ExpressMailIntlResponse / Regulations

required once

Additional regulations for shipping to destination country

string

 

ExpressMailIntlResponse / AdditionalRestrictions

required once

Additional restrictions for shipping to destination country. 

 

This tag is available when the request Revision tag >= 2.

If Revsion tag < 2, the additional restrictions are appended to the Restrictions tag

string

minOccurs=0

ExpressMailIntlResponse / InsuranceFee

optional

Insurance Fee

decimal

minExclusive=0.0

maxInclusive=5000

ExpressMailIntlResponse / DestinationBarcodeNumber

optional

Destination Barcode Number appears if mail class is available.

string

minOccurs=0

ExpressMailIntlResponse / GuaranteeAvailability

optional

Appears if ToPostalCode and LabelTime are available.  The value will be the GuaranteeDate or a message.

 

 

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 format will be a string, e.g.,

 

3 - 5 business days to many major markets

ExpressMailIntlCertifyResponse

required once

 

(alias)

 

 


 

 

Sample Response

Response:

ExpressMailIntlCertifyResponse>

  <Postage>61.00</Postage>

  <TotalValue>110.00</TotalValue>

  <SDRValue>65.09</SDRValue>

  <BarcodeNumber>ECXXXXXXXXXUS</BarcodeNumber>

  <LabelImage>SUkqAAgAAAASAP4ABAAB

    <!-- over 80000 suppressed -->

  </LabelImage>

  <Page2Image></Page2Image>

  <Page3Image></Page3Image>

  <Page4Image></Page4Image>

  <Page5Image></Page5Image>

  <Page6Image></Page6Image>

  <Prohibitions>Ammunition, firing caps, and loaded metal cartridges for portable firearms.Coins; banknotes; <!-- Data Truncated -->

<Observations>1. Goods whose commercial value exceed  <!-- Data Truncated -->

<Regulations>Country Code:MX  Reciprocal Service Name:  Servicio de Correspondencia Agrupada (SERCA) or Correos  <!-- Data Truncated -->

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

  <InsuranceFee>0</InsuranceFee>

  <GuaranteeAvailability>3-5 business days to many major markets</GuaranteeAvailability>

</ExpressMailIntlCertifyResponse>

 


 

Label Sample (4X6)

 

Error Responses

Error conditions are handled at the main XML document level and Package node 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].

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

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


 

Priority Mail International Label API

Overview

The Priority Mail Express International Label API lets customers generate Priority Mail Express International labels given the weight and dimensions of the item. 

API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PriorityMailIntl

&XML=(see Tag Descriptions below)

https://

secure.shippingapis.com

/ShippingAPI.dll

?API=PriorityMailIntlCertify

&XML=(see Tag Descriptions below)

 

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

Request Descriptions

Tag Name

Occurs

Description

Type

Validation

PriorityMailIntlRequest

required once

Produces a Priority Mail International label with customs declaration  

(group)

 

PriorityMailIntlRequest / @USERID

required

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

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. 

 

·      4X6LABEL (4X6 on a full page 8.5/11” background)

·      4X6LABELL (Landscape – true size 4X6; image rotated, not on an 8.5 x 11 background page)

·      4X6LABELP (Portrait – true size 4X6, not on an 8.5 x 11 background page)

 

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

string

Enumerations=

4X6LABEL

4X6LABELL

4X6LABELP

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  

Restriction enforced via truncation  

PriorityMailIntlRequest / FromCity

required once

For example: <FromCity>Anytown</FromCity>  

string

maxLength=16
minLength=1  

Restriction enforced via truncation  

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  

Restriction enforced via truncation  

PriorityMailIntlRequest / ToName

optional

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

string

maxLength=36

Restriction enforced via truncation  

PriorityMailIntlRequest / ToFirstName

optional

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

For example: <ToFirstName>John</ToFirstName> 

string

maxLength=30

Restriction enforced via truncation  

PriorityMailIntlRequest / ToLastName

optional

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

For example: <ToLastName>Doe</ToLastName> 

string

maxLength=30

Restriction enforced via truncation  

PriorityMailIntlRequest / ToFirm

optional

ToFirm is required if ToFirstName and ToLastName are left blank.

For example: <ToFirm></ToFirm> 

string

maxLength=36

Restriction enforced via truncation  

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  

Restriction enforced via truncation  

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  

Restriction enforced via truncation  

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  

Restriction enforced via truncation  

PriorityMailIntlRequest / ToCity

required once

Recipient's city.

 

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

string

maxLength=18
minLength=1  

Restriction enforced via truncation  

PriorityMailIntlRequest / ToProvince

optional

Enter the province for the recipient.

 

For example: <ToProvince>JALISCO</ToProvince>  

string

maxLength=9  

Restriction enforced via truncation  

PriorityMailIntlRequest / ToCountry

required once

The country name entered must match an entry from the USPS-approved International Index of Countries and Localities.

 

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  

Restriction enforced via truncation  

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

·   VARIABLE

·   LGFLATRATEBOX

·   SMFLATRATEBOX

·   MDFLATRATEBOX

·   FLATRATEENV

·   LEGALFLATRATEENV

·   PADDEDFLATRATEENV

·   SMFLATRATEENV

·   WINDOWFLATRATEENV

·   GIFTCARDFLATRATEENV

·   LGVIDEOBOX

·   RECTANGULAR

·   FLATRATEENV

·   NONRECTANGULAR 

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
minInclusive=1  

maxInclusive=999

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>490110490110</HSTariffNumber>  

String

whiteSpace=collapse
maxLength=12
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".

 

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

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

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

default=0  

PriorityMailIntlRequest / GrossOunces

required once

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

 

For example: <GrossOunces>0</GrossOunces>  

decimal

whiteSpace=collapse  

default=0.0

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. 

 

Note: enumerations are case sensitive

 

“NonnegotiableDocument” and “Documents” both signify mailable non-negotiable documents and are insured automatically for up to $100, though Insurance will not be returned as an extra service. Additional Insurance cannot be purchased. 

 

Any non-document ContentType values are insured automatically for up to $200 and Insurance will be returned as an explicit extra service in the response. Additional Insurance can be purchased for values $200 and greater.

string

enumerations=

·   MERCHANDISE

·   SAMPLE

·   GIFT

·   DOCUMENTS

·   RETURN

·   HUMANITARIAN

·   DANGEROUSGOODS

·   CrematedRemains

·   NonnegotiableDocument

·   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  

Restriction enforced via truncation  

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  

Restriction enforced via truncation  

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  

Restriction enforced via truncation  

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  

Restriction enforced via truncation  

PriorityMailIntlRequest / ImageType

required once

For example: <ImageType>PDF</ImageType>  

string

enumeration=PDF
enumeration=TIF
enumeration=NONE  

PriorityMailIntlRequest / ImageLayout

optional

Controls how the multipage form is returned in the response tags. "ONEPERFILE" returns one page per response tag while “ALLINONEFILE” returns all pages in a single response tag.

 

The “TRIM” options conserve page space if possible by combining two form parts on a single page.

 

For example:

<ImageLayout>ONEPERFILE<ImageLayout> 

string

default=ONEPERFILE
enumerations=

·      ONEPERFILE

·      ALLINONEFILE

·      TRIMONEPERFILE

·      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  

Restriction enforced via truncation  

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

minOccurs=0
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.

 

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

 

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

string

whiteSpace=collapse
minLength=0
maxLength=35

Restriction enforced via truncation  



PriorityMailIntlRequest / CommercialPrice

optional

Indicates if commercial-base price should be returned. For commercial-base price eligibility.

 

For example: <CommercialPrice>False</CommercialPrice>

string

default=false

enumeration=

TRUE

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> 

string

minOccurs=0  

 

PriorityMailIntlRequest / Width

 

optional

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


For example: <Length>11</Length> 

string

minOccurs=0  

 

PriorityMailIntlRequest / Height

 

optional

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


For example: <Height>11</Height> 

string

minOccurs=0  

 

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> 

string

minOccurs=0  

PriorityMailIntlRequest /MeterData

optional

Meter Data grouping.

(group)

 

FirstClassMailIntlRequest /MeterData/ MeterVendorID

optional

Meter Vendor ID, which is the 2 digit number USPS assigned vendor ID.

string

minLength value="0"

maxLength value="2"

 

PriorityMailIntlRequest /MeterData/ MeterSerialNumber

optional

Serial number of meter used for postage.

string

minLength value="0"

maxLength value="20"

 

PriorityMailIntlRequest /MeterData/ MeterModelID

optional

Two digit model number of the Meter

 

For example: PC-Postage models are 1 numeric followed by 1 alpha.

<MeterModelID>7a</MeterModelID>

string

minLength value="0"

maxLength value="15"

 

PriorityMailIntlRequest /MeterData/ RateCategory

optional

Four digit value denotes Product / Rate Category (As defined by the IBI data dictionary)

 

string

minLength value="0"

maxLength value="4"

               

PriorityMailIntlRequest / MeterData/ IndiciumCreationRecordDate

optional

Date IBI was created

Example: 12/19/2016

 

This tag is mostly used by PC Postage, metered and IMI PC Compliant customers

string

pattern value="\d{1,2}/\d{1,2}/\d{4}|"

PriorityMailIntlRequest /MeterData/IBI

optional

Information-Based Indicia (IBI)- Refers to a secure postage evidencing standard used by the United States Postal Service (USPS) to indicate electronic postage payment.

string

minLength value="0"

maxLength value="150"

               

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)

 

 

Sample Requests

All requests should hit the https://secure.shippingapis.com/ShippingAPI.dll end point with the API=PriorityMailIntl or PriorityMailIntlCertify and XML=<the sample XML request below> key value pairs using either a HTTP POST or a HTTP GET.

 

Request:

<PriorityMailIntlCertifyRequest USERID="xxx">

<Option/>

<Revision>2</Revision>

<ImageParameters>

<ImageParameter>4X6LABEL</ImageParameter>

</ImageParameters>

<FromFirstName>Garth</FromFirstName>

<FromMiddleInitial>A</FromMiddleInitial>

<FromLastName>Brooks</FromLastName>

<FromFirm>Garth's Firm</FromFirm>

<FromAddress1>radlab</FromAddress1>

<FromAddress2>6406 Ivy Lane</FromAddress2>

<FromUrbanization>Gary's Urbanization</FromUrbanization>

<FromCity>Greenbelt</FromCity>

<FromState>MD</FromState>

<FromZip5>20770</FromZip5>

<FromZip4>1234</FromZip4>

<FromPhone>3019187658</FromPhone>

<FromCustomsReference> From Customs Ref.</FromCustomsReference>

<ToName></ToName>

<ToFirstName>Reza</ToFirstName>

<ToLastName>Dianat</ToLastName>

<ToFirm>HP</ToFirm>

<ToAddress1>HP</ToAddress1>

<ToAddress2>5th floor</ToAddress2>

<ToAddress3>6406 Flower Lane</ToAddress3>

<ToCity>Greenbelt</ToCity>

<ToProvince>Md</ToProvince>

<ToCountry>Canada</ToCountry>

<ToPostalCode>20770</ToPostalCode>

<ToPOBoxFlag>N</ToPOBoxFlag>

<ToPhone>5555555555</ToPhone>

<ToFax>3012929999</ToFax>

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

<ToCustomsReference>Import Reference</ToCustomsReference>

<NonDeliveryOption>Return</NonDeliveryOption>

<Container>MDFLATRATEBOX</Container>

<ShippingContents>

<ItemDetail>

<Description>Description 1</Description>

<Quantity>1</Quantity>

<Value>1.11</Value>

<NetPounds>1</NetPounds>

<NetOunces>1</NetOunces>

<HSTariffNumber>123456789123</HSTariffNumber>

<CountryOfOrigin>Brazil</CountryOfOrigin>

</ItemDetail><ItemDetail>

<Description>Description 2</Description>

<Quantity>2</Quantity>

<Value>2.22</Value>

<NetPounds></NetPounds>

<NetOunces>2</NetOunces>

<HSTariffNumber>234567</HSTariffNumber>

<CountryOfOrigin>Switzerland</CountryOfOrigin>

</ItemDetail><ItemDetail>

<Description>Description 3</Description>

<Quantity>3</Quantity>

<Value>3.33</Value>

<NetPounds></NetPounds>

<NetOunces>3</NetOunces>

<HSTariffNumber>123456789123</HSTariffNumber>

<CountryOfOrigin>Brazil</CountryOfOrigin>

</ItemDetail><ItemDetail>

<Description>Description 4</Description>

<Quantity>4</Quantity>

<Value>4.44</Value>

<NetPounds></NetPounds>

<NetOunces>4</NetOunces>

<HSTariffNumber>234567234567</HSTariffNumber>

<CountryOfOrigin>Switzerland</CountryOfOrigin>

</ItemDetail>

</ShippingContents>

<Insured>N</Insured>

<InsuredNumber>90123</InsuredNumber>

<InsuredAmount>99.90</InsuredAmount>

<GrossPounds>3</GrossPounds>

<GrossOunces>8</GrossOunces>

<ContentType>Documents</ContentType>

<ContentTypeOther>and Other</ContentTypeOther>

<Agreement>Y</Agreement>

<Comments>PriorityMailIntl Comments</Comments>

<LicenseNumber>Lic# 123</LicenseNumber>

<CertificateNumber>Cert#456</CertificateNumber>

<InvoiceNumber>Inv#890</InvoiceNumber>

<ImageType>TIF</ImageType>

<ImageLayout>TRIMONEPERFILE</ImageLayout>

<CustomerRefNo>Cust Ref#123</CustomerRefNo>

<POZipCode>20770</POZipCode>

<LabelDate></LabelDate>

<HoldForManifest>N</HoldForManifest>

<EELPFC>802.11B</EELPFC>

<CommercialPrice></CommercialPrice>

<Size></Size>

<Length></Length>

<Width></Width>

<Height></Height>

<Girth></Girth>

<ExtraServices><ExtraService></ExtraService>

</ExtraServices>

</PriorityMailIntlCertifyRequest>

 


 

Response Descriptions

Tag Name

Occurs

Description

Type

Validation

PriorityMailIntlResponse

required once

 

(group)

 

PriorityMailIntlResponse / Postage

required once

Postage amount  

decimal

 

PriorityMailIntlResponse / TotalValue

required once

Value of all items being shipped  

decimal

 

PriorityMailIntlResponse / SDRValue

required once

Special Drawing Right calculated on Insured Amount

decimal

 

PriorityMailIntlResponse / BarcodeNumber

required once

Mail service related barcode, may be empty  

string

 

PriorityMailIntlResponse / LabelImage

required once

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

base64Binary

 

PriorityMailIntlResponse / Page2Image

required once

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

base64Binary

 

PriorityMailIntlResponse / Page3Image

required once

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

base64Binary

 

PriorityMailIntlResponse / Page4Image

required once

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

base64Binary

 

PriorityMailIntlResponse / Page5Image

required once

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

base64Binary

 

PriorityMailIntlResponse / Page6Image

required once

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

base64Binary

 

PriorityMailIntlResponse / Prohibitions

required once

List of items prohibited from mailing based on country of destination  

string

 

PriorityMailIntlResponse / Restrictions

required once

Restrictions on items being shipped based on country of destination  

string

 

PriorityMailIntlResponse / Observations

required once

Additional mailing information based on country of destination  

string

 

PriorityMailIntlResponse / Regulations

required once

Additional regulations for shipping to destination country  

string

 

PriorityMailIntlResponse / AdditionalRestrictions

required once

Additional restrictions on items being shipped to destination country

string

 

PriorityMailIntlResponse / DestinationBarcodeNumber

optional

Destination Barcode Number appears if mail class is available.

string

 

PriorityMailIntlResponse / ParcelIndemnityCoverage

required once

Indemnity value  

decimal