USPS Web Tools™ Application Programming Interface User Guide Version 3.4 (02/19/2021)
USPS Web Tools API User Guide Table of Contents 1.0 Introduction to Web Tools ...... 4 1.1 Before you get started: ...... 4 2.0 eVS Priority Mail Express International Label API ...... 5 2.1 Overview ...... 5 2.1.1 API Signature ...... 5 2.2 Request Descriptions ...... 5 2.2.1 Sample Request ...... 18 2.3 Response Descriptions ...... 19 2.3.1 Sample Response ...... 21 3.0 eVS Priority Mail International Label API ...... 22 3.1 Overview ...... 22 3.1.1 API Signature ...... 22 3.2 Request Descriptions ...... 23 3.2.1 Sample Request ...... 36 3.3 Response Descriptions ...... 38 3.3.1 Sample Response ...... 40 4.0 eVS First Class Mail International Label API ...... 42 4.1 Overview ...... 42 4.1.1 API Signature ...... 43 4.2 Request Descriptions ...... 43 4.2.1 Sample Request ...... 55 4.3 Response Descriptions ...... 56 4.3.1 Sample Response ...... 57 5.0 eVS GXG Get Label API ...... 59 5.1 Overview ...... 59 5.1.1 API Signature ...... 59 5.2 Request Descriptions ...... 59 5.2.1 Sample Request ...... 70 5.3 Response Descriptions ...... 72 5.3.1 Sample Response ...... 73 6.0 eVS International Cancel API ...... 74 6.1 Overview ...... 74 6.1.1 API Signature ...... 74 6.2 Request Descriptions ...... 74 6.2.1 Sample Request ...... 74
2
USPS Web Tools API User Guide
6.3 Response Descriptions ...... 74 6.3.1 Sample Response ...... 75 7.0 Appendix A ...... 76 7.1 eVS International Label Example – Express Mail International ...... 76 7.2 eVS International Label Example – Priority Mail International ...... 77 7.3 eVS International Label Example – First Class Mail International ...... 78 7.4 eVS International Label Example – GXG Get Label ...... 79 8.0 Appendix B ...... 80 8.1 Country Codes ...... 80
3
USPS Web Tools API User Guide 1.0 Introduction to Web Tools This document contains a Reference Guide to the eVS international label APIs: Priority Mail Express International, Priority Mail International, Global Express Guaranteed (see section IV for limitations) and First Class Mail International (First Class Package International Service). See the Developers 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 troubleshooting. 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: 2 In this instance, you will replace “2” with the weight in pounds for the package. 1.1 Before you get started: The only option for creating labels through our APIs requires eVS setup/enrollment. In general, eVS: • Requires 50 pieces or 50 pounds per mailing • Requires a permit imprint • Requires payment via ACH debit daily (no other forms of payment) • Handles origin entered mail (no destination entry or presort) • Requires enrollment and new Mailer IDs (MIDs) and permits • Supports domestic/international/APO/FPO/DPO/PTFAS locations eVS, or Electronic Verification System, allows high-volume package mailers and package consolidators to document and pay postage, including special service fees, using electronic manifest files. The files are transmitted over the Internet to a Postal Service™ database. eVS is designed to make it easy for high-volume package mailers to take advantage of destination entry rates. If you want to explore using eVS, please first contact the [email protected]. For registration please visit: https://www.usps.com/postalone/evs.htm. If that will not work for you, then you can follow up with [email protected] (or your local Postmaster or USPS Sales Manager) for additional solutions outside of the Web Tools API suite. Note: The “Certify” API signatures are for testing purposes and will not generate usable labels and barcodes. Whether you are a new or existing mailer, USPS strongly suggests a conversation with you to discuss your business requirements so your account will be properly configured. To initiate this conversation please contact the National Customer Support Center (NCSC) at 877-264-9693 Option 4 and request a referral to an Operations Integration Specialist (OIS) and Technical Integration Specialist (TIS). USPS will align the appropriate team to assist with swift onboarding. Depending on your needs, your account may be configured in many flexible ways; however, each account will be configured with credentials in a master/child relationship. Minimally, credentials will be established as follows: • A master Mailer ID is created o Child Mailer IDs are created for each origin site and may be created as needed by the requirements of your business units and brands. • A permit number is created o Additional permit numbers may be created as needed by the requirements of your business units and brands 4
USPS Web Tools API User Guide
• A CAPS Debit account is created for payment processing o Additional CAPS Debit accounts may be created as needed Your Operations Integration Specialist and Technical Integration Specialist will be involved at the local and national levels to ensure successful launch and introduction to appropriate production support teams. For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Web Tools Technical Documentation Page. 2.0 eVS Priority Mail Express International Label API 2.1 Overview The eVS Priority Mail Express International Label API lets customers generate eVS Priority Mail Express International labels and integrated customs forms.
Note: Scan form is eligible for eVS if HoldForManifest is set to ‘Y’ (Yes).
Note: The “eVSExpressMailIntlCertify” API signature is for testing purposes and will not generate usable labels and barcodes. 2.1.1 API Signature Scheme Host Path API XML https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSExpressMailIntl &XML=(see Tag Descriptions below) https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSExpressMailIntl &XML=(see Tag Certify Descriptions below) 2.2 Request Descriptions
Tag Name Occurs Description Type Validation eVSExpressMailIntl Required (Alias) Request eVSExpressMailIntl Required This attribute specifies your WebTools ID. NMTOKE Request / USERID See the Developers Guide for information on N obtaining your USERID. For example: eVSExpressMailIntl Optional For future use. Empty Request / Option eVSExpressMailIntl Optional Use of value 2 Required as of January 2011. String minLength=0 Request / Revision For example: 2 pattern=\d{1} pattern= eVSExpressMailIntl Optional Groups alternate image options. (Group) Request / ImageParameters eVSExpressMailIntl Optional, Returns alternate label image. Only String Enumerations= Request / repeating alternate 4’’x6’’ size label image may be • 4X6LABEL ImageParameters / up to 3 requested at this time. • 4X6LABELL ImageParameter times • 4X6LABEL - (4X6 on a full page 8.5/11” • 4X6LABELP background) • 4X6ZPL203DPI • 4X6ZPL300DPI
5
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
• 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) • 4X6ZPL203DPI - (ZPL - Zebra Programming Language) format. When using this enumeration, is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response. • 4X6ZPL300DPI - Prints a label formatted for ZPL printers in 300 dpi. When using this enumeration, is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response. For example: 4X6LABEL eVSExpressMailIntl Required Both FromFirstName and FromLastName String maxLength=30 Request / are Required if FromFirmName is left blank. minLength=0 FromFirstName Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: John eVSExpressMailIntl Optional Middle Initial. Maximum Length: 32 String maxLength=1 Request / characters total for First, Middle, and Last FromMiddleInitial Names with space after first and middle name. For example: L eVSExpressMailIntl Required Both FromFirstName and FromLastName String maxLength=30 Request / are Required if FromFirmName is left blank. minLength=0 FromLastName Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: Doe eVSExpressMailIntl Required FromFirm is Required if FromFirstName and String maxLength=32 Request / FromFirm FromLastName are left blank. For example: ABC Corp
6
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSExpressMailIntl Optional Use this tag for a suite or apartment number String maxLength=32 Request / only. Either Address1 or Address2 is FromAddress1 Required. For example: Suite 101 eVSExpressMailIntl Required Use this tag for the primary address line. String maxLength=32 Request / For example: 10 Elm FromAddress2 Street eVSExpressMailIntl Optional Use this tag for Puerto Rico only. ZIP Code String maxLength=32 Request / prefixes 006 to 009, if area is so designated. FromUrbanization For example: URB Caparra Ter eVSExpressMailIntl Required For example: Bristol String maxLength=16 Request / FromCity minLength=1 eVSExpressMailIntl Required Use 2-letter USPS state abbreviation. String length=2 Request / FromState For example: CT eVSExpressMailIntl Required Input tag exactly as presented, not all caps. String whiteSpace=collapse Request / FromZip5 5 digits Required. length=5 For example: pattern=\d{5} 06010 eVSExpressMailIntl Optional Input tag exactly as presented, not all caps. String whiteSpace=collapse Request / FromZip4 If value is entered, 4 digits Required. This is length=4 the ZIP+4 extension. pattern=\d{4} For example: 5678 eVSExpressMailIntl Required 10 digits Required (including area code), String whiteSpace=collapse Request / with no punctuation. Use format: length=10 FromPhone 2125551234 pattern=\d{10} For example: 5555555555 eVSExpressMailIntl Optional Enter a value for the "Sender's Customs String maxLength=30 Request / Reference" that will appear on the label. The FromCustomsRefer text entered is any reference number that ence the sender wishes to use. For example: eVSExpressMailIntl Optional Deprecated. See “ToFirstName” and String maxLength=36 Request / ToName “ToLastName” tags. eVSExpressMailIntl Required Both ToFirstName and ToLastName are String maxLength=30 Request / Required if ToFirm is left blank. ToFirstName For example: John eVSExpressMailIntl Required Both ToFirstName and ToLastName are String maxLength=30 Request / Required if ToFirm is left blank. ToLastName For example: Doe eVSExpressMailIntl Required ToFirm is Required if ToFirstName and String maxLength=36 Request / ToFirm ToLastName are left blank.
7
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: ABC Co eVSExpressMailIntl Optional Three address lines are provided, but only 1 String maxLength=36 Request / is Required. Use as many as needed for minLength=1 ToAddress1 complete address. For example: 60 Carlton St eVSExpressMailIntl Required Three address lines are provided, but only 1 String maxLength=36 Request / is Required. Use as many as needed for ToAddress2 complete address. eVSExpressMailIntl Optional Three address lines are provided, but only 1 String maxLength=36 Request / is Required. Use as many as needed for ToAddress3 complete address. eVSExpressMailIntl Required Recipient's city. String maxLength=18 Request / ToCity For example: Toronto minLength=1 eVSExpressMailIntl Optional Enter the province for the recipient. String maxLength=9 Request / For example: ToProvince ON eVSExpressMailIntl Required The country name entered must match an String minLength=1 Request / ToCountry 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: Canada eVSExpressMailIntl Required Enter the postal code for the recipient. String maxLength=9 Request / For example: M5B ToPostalCode 1J2 eVSExpressMailIntl Required Indicates whether the destination address is String Enumerations= Request / a Post OfficeBox. • Y ToPOBoxFlag For example: • N N eVSExpressMailIntl Optional No format checking is done on international String maxLength=30 Request / ToPhone phone numbers. Required when Y For example: 011 52 (322) 222- 0069 eVSExpressMailIntl Optional No format checking is done on international String maxLength=30 Request / ToFax fax numbers. For example: 011 52 (322) 222- 0074 eVSExpressMailIntl Optional Complete valid e-mail address is Required if String maxLength=30 Request / ToEmail tag is used. whiteSpace=collapse For example: pattern=([\w\- [email protected] \.]+)@(([\w-]+\.)+)[a- zA-Z]{2,4} eVSExpressMailIntl Optional Enter a value for the "Importer's Customs String maxLength=28 Request / Reference" that will appear on the label. The
8
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
ImportersReference text entered is any reference number that Number the recipient wishes to use. For example: Order 23432 eVSExpressMailIntl Optional In case package is undeliverable, enter one String Enumerations= Request / of the following: "RETURN" for package to • RETURN NonDeliveryOption be returned to above. • REDIRECT "REDIRECT" to return package to address • ABANDON specified below in tags. "ABANDON" to dispose of undeliverable package. For example: RETURN eVSExpressMailIntl Optional Enter a value for the recipient's name. String minOccurs=0 Request / RedirectName eVSExpressMailIntl Optional Complete valid e-mail address is required if String minOccurs=0 Request / tag is used. RedirectEmail eVSExpressMailIntl Optional This value must be a syntactically valid SMS String minOccurs=0 Request / number. RedirectSMS eVSExpressMailIntl Optional Enter the redirect address. This is a free String minOccurs=0 Request / form field. maxLength=48 RedirectAddress eVSExpressMailIntl Optional Redirect city. String minLength=0 Request / For example: maxLength=21 RedirectCity ANYTOWN eVSExpressMailIntl Optional Redirect state. String minLength=0 Request / For example: pattern=\w{2} RedirectState MN eVSExpressMailIntl Optional Redirect ZIP code. String minLength=0 Request / For example: pattern=\d{5} RedirectZipCode 12345 eVSExpressMailIntl Optional Redirect ZIP+4 extension. String minLength=0 Request / For example: RedirectZip4 01234 eVSExpressMailIntl Optional Container type. String Enumerations= Request / Container • VARIABLE • FLATRATEENV • LEGALFLATRAT EENV • PADDEDFLATR ATEENV
9
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSExpressMailIntl Required (Group) Request / ShippingContents eVSExpressMailIntl Required (Group) maxOccurs=”30" Request / repeating ShippingContents / up to 30 ItemDetail times eVSExpressMailIntl Required Description of the item. String maxLength=30 Request / For example: Policy guidelines minLength=1 ShippingContents / document whiteSpace=collapse ItemDetail / Description eVSExpressMailIntl Required Quantity of the item. Integer value Required. integer minInclusive Request / For example: 1 value="1" ShippingContents / maxInclusive ItemDetail / Quantity value="999" eVSExpressMailIntl Required The data entered with this tag provides the decimal whiteSpace=collapse Request / value of the set of items. If the item is 2 minExclusive=0 ShippingContents / boxes of 50 pens and the value of each box ItemDetail / Value 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: 55.00 eVSExpressMailIntl Required Provide the pounds component of the weight integer whiteSpace=collapse Request / of the individual item listed with default=0 ShippingContents / . ItemDetail / For example: 1 NetPounds eVSExpressMailIntl Required Provide the ounces component of the weight decimal default="0.0" Request / of the individual item listed with ShippingContents / . ItemDetail / For example: 5 NetOunces eVSExpressMailIntl Required For commercial items only. If known, the HS String whiteSpace=collapse Request / tariff number must be based on the maxLength=12 ShippingContents / Harmonized Commodity Description and pattern=\d{0,12} ItemDetail / Coding System developed by the World HSTariffNumber Customs Organization. For example: 490110 eVSExpressMailIntl Required String For commercial items only. Country of Origin Request / means the country where the goods ShippingContents / originated, e.g. were produced, ItemDetail / manufactured, or assembled. It is CountryOfOrigin recommended you supply this information and attach an invoice to the outside to accelerate customs clearance in processing
10
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
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: United States eVSExpressMailIntl Optional For backward compatibility; not validated. String Request / InsuredNumber eVSExpressMailIntl Optional Use this tag for entering an insurance String length=0 Request / amount, if known. InsuredAmount For example: 100.00 eVSExpressMailIntl Optional Use this tag for entering a postage amount, String length=0 Request / Postage if known. If the tag is present, but the value is blank, the postage will be automatically calculated. For example: 10.50 eVSExpressMailIntl Required Gross pounds and ounces together integer whiteSpace=collapse Request / represent the total package weight, including GrossPounds packing material. For example, a package weighing 3 lbs 8 ounces would have "3" entered here and "8" entered with the 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: 4 eVSExpressMailIntl Required Enter the ounces component of the total integer maxLength=3 Request / package weight with this tag. GrossOunces For example: 0 eVSExpressMailIntl Required Specifies the content of the package or String Enumerations= Request / envelope. • MERCHANDISE ContentType For example: • SAMPLE DOCUMENTS • DOCUMENTS Note : “NONNEGOTIABLEDOCUMENT” • RETURN and “DOCUMENTS” both signify mailable • HUMANITARIAN non-negotiable documents and are insured • DANGEROUSG automatically for up to $100, though OODS Insurance will not be returned as an extra • CREMATEDREM service. Additional Insurance cannot be AINS purchased. Any non-document
11
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
values are insured • NONNEGOTIABL automatically for up to $200. Additional EDOCUMENT Insurance can be purchased for values $200 • PHARMACUTIC and greater. ALS • MEDICALSUPPL IES • OTHER eVSExpressMailIntl Optional Required when String maxLength=15 Request / OTHER. whiteSpace=collapse ContentTypeOther eVSExpressMailIntl Required Requires a value of “Y” to print String Enumerations= Request / and • Y Agreement in Signature Box along with Current Date • N (Central Time USA). Any other value returns an error. eVSExpressMailIntl Optional Enter any comments. String maxLength=76 Request / For example: Comments eVSExpressMailIntl eVSExpressMailIntl Optional Enter license number, if known or if included String maxLength=24 Request / in package. LicenseNumber For example: LIC- 24356879 eVSExpressMailIntl Optional Enter certificate number, if known or if String maxLength=24 Request / included in package. CertificateNumber For example: CERT- 97865342 eVSExpressMailIntl Optional Enter invoice number, if known or if included String maxLength=24 Request / in package. InvoiceNumber For example: INV- 040903 eVSExpressMailIntl Required Label Image Type. Note: All String Enumerations= Request / values are ignored when • PDF ImageType = “4X6ZPL203DPI” or “4X6ZPL300DPI”. • TIF For example: • NONE PDF eVSExpressMailIntl Optional Controls how the multipage form is returned String Enumerations= Request / in the response tags. "ONEPERFILE" • ONEPERFILE ImageLayout returns one page per response tag while • ALLINONEFILE “ALLINONEFILE” returns all pages in a • TRIMONEPERFI single response tag. LE The “TRIM” options conserve page space if • TRIMALLINONE possible, by combining two form parts on a FILE single page. For example: ONEPERFILE
12
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSExpressMailIntl Optional Written to Postal Manifest Detail record. String maxLength=30 Request / For example: Ref CustomerRefNo 369246 eVSExpressMailIntl Optional Written to Postal Manifest Detail record. String maxLength=30 Request / For example: CustomerRefNo2 ACT369246 eVSExpressMailIntl Optional ZIP Code of Post Office or collection box String whiteSpace=collapse Request / where item is mailed. May be different than length=5 POZipCode FromZip5. This tag will take precedence pattern=\d{5} over FromZip5 when provided. For example: 00962 eVSExpressMailIntl Optional Date the mail will enter the mail stream. No String whiteSpace=collapse Request / LabelDate more than 3 days in the future. Default is maxLength=10 day of request. pattern=\d{1,2}/\d{1,2} For example: /\d\d(\d\d)? 09/28/2010 eVSExpressMailIntl Optional For future use. USPS Corporate Account minOccurs=0 Request / EMCAAccount eVSExpressMailIntl Optional Restricted use. Holds manifest record for String Enumerations= Request / possible inclusion in SCAN request. • Y HoldForManifest • N eVSExpressMailIntl Optional Exemption and Exclusion Legend or PFC String minOccurs=0 Request / EELPFC repeating Code. maxOccurs=1 up to 1 Please refer to the International Mail Manual time for further information: http://pe.usps.gov/text/imm/immc5_007.htm. For example: 30.37a eVSExpressMailIntl Optional Indicates if commercial-base price should be String Enumerations= Request / returned. For commercial-base price • COMMERCIAL PriceOptions eligibility, please reference the Domestic PLUS Mail Manual at http://pe.usps.com/. • COMMERCIAL BASE eVSExpressMailIntl Optional Value must be numeric. Units are inches. If String minOccurs=0 Request / Length partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.
13
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSExpressMailIntl Optional Value must be numeric. Units are inches. If String minOccurs=0 Request / Width partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSExpressMailIntl Optional Value must be numeric. Units are inches. If String minOccurs=0 Request / Height partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSExpressMailIntl Optional Value must be numeric. Units are inches. If String minOccurs=0 Request / Girth partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be
14
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
left blank as this dimension is to only be used for non-rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSExpressMailIntl Optional Available if = 2. String Format hh:mm Request / LabelTime LabelTime is used in conjunction with LabelDate to determine the Guarantee eVSExpressMailIntl Optional Meter payment indicator String Enumerations= Request / • N MeterPaymentFlag • Y eVSExpressMailIntl Optional Used to specify the action code.Value is String Enumerations= Request / passed to Shipping Partner Event file via the • M0 ActionCode shipment manifest. • S0 • M0 – Mailer Owner • S0 – Service Provider For example: M0 eVSExpressMailIntl Optional Allows a customer to opt out of SPE file Boolean Enumerations= Request / creation. “false” WILL create a SPE file. • true OptOutOfSPE Note: This request tag is case sensitive. • false eVSExpressMailIntl Optional Number associated with a mailing permit. String minOccurs=0 Request / The permit is permission to use a certain PermitNumber postage payment method for bulk and commercial mailings eVSExpressMailIntl Optional ZIP of Account Post Office where mailed if String whiteSpace=collapse Request / different from . Written to Postal length=5 AccountZipCode Manifest Detail record. Must be valid ZIP pattern=\d{5} Code. For example: 00962 eVSExpressMailIntl Optional Tax code / VAT no. / Importer Code. String minOccurs=0 Request / Enumerations= ImportersReference • TAXCODE Type • VAT • IMPORTERCOD E eVSExpressMailIntl Optional For Importer: 10 digits (including area code), String whiteSpace=collapse Request / with no punctuation. length=10 ImportersTelephone Use format: 2125551234 pattern=\d{10} Number For example: 5555555555< /ImportersTelephoneNumber>
15
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSExpressMailIntl Optional For Importer: No format checking is done on String maxLength=30 Request / international fax numbers. ImportersFaxNumbe For example: 011 52 r (322) 222-0074 eVSExpressMailIntl Optional For Importer: Complete valid e-mail address String maxLength=30 Request / is Required if tag is used. whiteSpace=collapse ImportersEmail For example: pattern=([\w\- [email protected] zA-Z]{2,4} eVSExpressMailIntl Optional Indicates whether the item is machinable. Boolean default=true Request / For example: whiteSpace=collapse Machinable false eVSExpressMailIntl Required Required for destination entry packages String Enumerations= Request / enter either “I” or “N”. • I DestinationRateIndic • I= International Service Center • N ator (ISC) • N = None eVSExpressMailIntl Optional Mailer ID (MID), Represents Mail Owner String Length=6 or 9 Request / MID MID. positions, if populated Located in position #13 in the Detail 1 record of the Shipping Services File v2.0. For example: 847654321 eVSExpressMailIntl Optional The MID of the company that manages the String Length=6 or 9 Request / mailing. positions, if populated LogisticsManagerMI Located in position #12 in the Detail 1 record D of the Shipping Services File v2.0. Note: If LogisticsManagerMID is populated, either CRID or MID must also be populated. For example: 489001< / LogisticsManagerMID> eVSExpressMailIntl Optional Customer Registration ID, Represents Mail String minLength=0 Request / CRID Owner CRID. maxLength=15 Located in position #20 in the Detail 1 record of the Shipping Services File v2.0. For example: 544762 eVSExpressMailIntl Optional Code from vendor software to identify the String minLength=0 Request / developer of the shipping system. maxLength=4 VendorCode Located in position #15 in the Detail 1 record default=8300 of the Shipping Services File v2.0. For example: 1234 eVSExpressMailIntl Optional Shipping software’s product version number. String minLength=0 Request / Located in position #16 in the Detail 1 record maxLength=8 VendorProductVersi of the Shipping Services File v2.0. onNumber For example: 5.02.1B
16
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSExpressMailIntl Optional Verifies Sender Information, sender fields String Enumerations= Request / must match From information when • 1 ePostageMailerRep =1 • 2 orting • 1 - (ePostage sender information in • 3 SSF) • 2 - (ePostage sender information through DES) • 3 - (ePostage sender information using child MID) eVSExpressMailIntl Optional First Name of Sender. String minLength=0 Request / For example: Adam maxLength=49 SenderFirstName Required when =1 eVSExpressMailIntl Optional Last Name of Sender. String minLength=0 Request / For example: Smith maxLength=75 SenderLastName Required when =1 eVSExpressMailIntl Optional Values for Sender Business Name must be String minLength=0 Request / sent. maxLength=100 SenderBusinessNa For example: me USPS eVSExpressMailIntl Optional Sender address line. Use this tag for full String minLength=0 Request / address (Address1 and Address2) maxLength=148 SenderAddress1 Must match Address1 and Address2 or will produce an error. For example: STE 150 10 Elm Street Required when =1 eVSExpressMailIntl Optional Sender city. String minLength=0 Request / For example: maxLength=50 SenderCity BETHESDAReq uired when =1 eVSExpressMailIntl Optional Sender state. String minLength=0 Request / For example: maxLength=2 SenderState MD Required when =1 eVSExpressMailIntl Optional Sender ZIP code. String minLength=0 Request / For example: pattern=d(5) SenderZip5 20212 Required when =1 eVSExpressMailIntl Optional Sender Phone #. 10 digits Required String minLength=0 Request / (including area code), with no punctuation. pattern=d(10) SenderPhone
17
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: 2125551234 Required when =1 eVSExpressMailIntl Optional E-mail Address of Sender. Valid e-mail String minLength=0 Request / addresses must be used. pattern=([\w\- SenderEmail For example: \.]+)@(([\w-]+\.)+)[a- [email protected] Required when =1 eVSExpressMailIntR Required (Alias) equest 2.2.1 Sample Request Request: eVSExpressMailIntlRequest 24X6LABELJosephJJonesPostal ServiceSuite 101901 D Street SWWashingtonDC200246129919888765245655332JonJohnCoffee FiveR. da Quitanda, 86 - quiosque 01CentroRio de JaneiroBRAZIL20091-902N77712345673012929999[email protected]E382788RETURNVARIABLE
Tag Name Occurs Description Type Validation eVSExpressMailIntlResponse Required (Alias) eVSExpressMailIntlResponse/ Required Postage amount Decimal Postage eVSExpressMailIntlResponse/ Required Value of all items being shipped Decimal TotalValue eVSExpressMailIntlResponse/ Required Special Drawing Right calculated on Decimal SDRValue Insured Amount
19
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSExpressMailIntlResponse/ Required Mail service related barcode. String BarcodeNumber eVSExpressMailIntlResponse/ Required Encoded images of label (may be String LabelImage empty depending upon layout option selected) eVSExpressMailIntlResponse/ Required Encoded images of label (may be String Page2Image empty depending upon layout option selected) eVSExpressMailIntlResponse/ Required Encoded images of label (may be String Page3Image empty depending upon layout option selected) eVSExpressMailIntlResponse/ Required Encoded images of label (may be String Page4Image empty depending upon layout option selected) eVSExpressMailIntlResponse/ Required Encoded images of label (may be String Page5Image empty depending upon layout option selected) eVSExpressMailIntlResponse/ Required Encoded images of label (may be String Page6Image empty depending upon layout option selected) eVSExpressMailIntlResponse/ Required List of items prohibited from mailing String Prohibitions based on country of destination eVSExpressMailIntlResponse/ Required Restrictions on items being shipped String Restrictions based on country of destination eVSExpressMailIntlResponse/ Required Additional mailing information String Observations based on country of destination eVSExpressMailIntlResponse/ Required Additional regulations for shipping String Regulations to destination country eVSExpressMailIntlResponse/ Required Additional restrictions on items String AdditionalRestrictions being shipped to destination country eVSExpressMailIntlResponse/ Optional Insurance Fee Decimal minExclusive=0.0 InsuranceFee maxInclusive=5000 eVSExpressMailIntlResponse/ Optional Appears if mail class is available. String minoccurs=0 DestinationBarcodeNumber eVSExpressMailIntlResponse/ Optional Appears if ToPostalCode and String GuaranteeAvailability LabelTime are available. The value will be the GuaranteeDate or a message. If an estimated scheduled delivery date is available, the format will be MM/DD/YYYY e.g. 03/15/2015. 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
20
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSExpressMailIntlResponse/ Required This contains the number of String RemainingBarcodes remaining barcodes that can be generated for this particular request. eVSExpressMailIntlResponse/ Optional String Warning eVSExpressMailIntlResponse Required (Alias) 2.3.1 Sample Response Response:eVSExpressMailIntl 67.8415.0010.83EB321424860US.....removed..........removed..........removed..........removed..........removed..... Banknotes; currency notes; paper money; securities payable to bearer; and traveler's checks. Coins; manufactured and unmanufactured platinum, gold, and silver; precious stones; jewels; expensive jewelry; and other valuable articles. Commercial samples that promote tobacco products or smoking-related merchandise. Commercial shipments that contain cigarettes, cigarillos, cigars, loose and packaged tobacco, pipes, and other smoking devices. Items that are fragile, either by nature or due to inadequate packing, that could cause harm to individuals or equipment. Medicines whose formulas are not listed in the official pharmacopeias or not licensed by the Brazilian Department of Public Health. Perishable infectious biological substances. Perishable noninfectious biological substances. Playing cards. Poniards, stilettos, poniard blades; canes, umbrellas, or any other articles containing swords, daggers, or guns; handcuffs, and blackjacks. Primary educational books not written in Portuguese. Radioactive materials. Regulation arms and munitions of Brazil and parts. Air guns. Reducing tubes and silencers for firearms. Salted or smoked meat, and other foodstuffs of animal origin. Seeds and seedlings of coffee, shrubs. Used consumer goods (See Observation #5 for exception). Medicines must be accompanied by a prescription from the attendant Brazilian doctor. This prescription should be on a chemist's form, bearing the name, private address or office of the doctor, his registration number with the Brazil National Medical Council and a Portuguese translation of the instructions, as necessary. Postal packages containing medicaments and not satisfying the above-mentioned conditions will be returned to the senders or, if abandoned, treated as undeliverable items. Postage stamps are admitted only in registered First- Class Package International Service with Registered Mail service shipments. Saccharine and other artificial sweeteners for artificial beverages require permission from the Brazilian Department of Public Health for importation. 1. Empresa Brasileira de Correios e Telégrafos (ECT) is introducing a "Fee for Postal Dispatch" with a current value of 15 Brazilian reals (BRL) for items presented to customs. If the addressee has not properly paid this fee, ECT will return the item to the sender. 2. Import licenses are required for many kinds of goods. ECT recommends that the sender ascertain from the addressee before mailing that the addressee holds the necessary documents. A shipment that does not have a required import permit is subject to confiscation as
21
USPS Web Tools API User Guide
contraband. 3. The mailer must affix all necessary or relevant documents including invoices, export/import licenses, certificates of origin, health certificates, etc., to the outside of the item. 4. Imports are allowed by mail, including mail order catalog shipments, up to a value of U.S. $500 (U.S. $1,000 for computer software) without the requirement of an import license provided the item is not for resale. Shipments valued at no more than U.S. $50 are duty-free and are delivered to the addressee; shipments above U.S. $50 can be picked up at the post office upon payment of import duties. Imports that are prohibited or subject to special regulations must comply with applicable Brazilian government provisions. Identical shipments from the same source to the same person or address in Brazil within a 90-day period are considered part of the same shipment and may be subject to confiscation. Other merchandise that usually enters duty-free include items such as newspapers, maps, books, and magazines. 5. The mailer must fully and accurately complete the customs declarations, including the landline or mobile telephone number of the addressee, if available, and detailed information concerning the contents and value of the item, such as branded product description, model, serial number, and value of each individual article within the item. ECT immediately returns to the sender an item that does not have a properly completed customs declaration. 6. The importer tax identification (ID) number is required for all items containing goods. In Brazil, the importer tax ID number is known as "CPF" (format: 000.000.000-00) for natural persons and as "CNPJ" (format: 00.000.000/0000-00) for legal persons. This information must be provided either by the mailer in the importer reference field of the customs declaration form or on the commercial invoice, or by the importer through the Correios website at www2.correios.com.br/sistemas/rastreamento. 7. Shipments that do not indicate the applicable postage and fees on PS Form 2976-A will hinder the customs clearance process, causing delays to clear the items. 8. Used consumer goods may only be sent to charitable organizations that are recognized by the Brazilian government as being entities which serve the public interest. Country Code: BR Reciprocal Service Name; Serca Required Customs Form/Endorsement 1. Correspondence and business papers. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Endorse item clearly next to mailing label as BUSINESS PAPERS. 2. Merchandise, merchandise samples without commercial value, documents, computer data, and all articles subject to customs duty. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Include an invoice with all commercial shipments. Note: Coins; banknotes; currency notes, including paper money; securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver; precious stones; jewelry; watches; and other valuable articles are prohibited in Priority Mail Express International shipments to Brazil. Areas Served: All No Additional Restrictions Data found.03-5 business days to many major markets9773
3.0 eVS Priority Mail International Label API 3.1 Overview The eVS Priority Mail Express International Label API lets customers generate eVS Priority Mail Express International labels given the weight and dimensions of the item.
Note: The “eVSPriorityMailIntlCertify” API signature is for testing purposes and will not generate usable labels and barcodes. 3.1.1 API Signature Scheme Host Path API XML https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSPriorityMailIntl &XML=(see Tag Descriptions below) https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSPriorityMailIntl &XML=(see Tag Certify Descriptions below)
22
USPS Web Tools API User Guide
3.2 Request Descriptions
Tag Name Occurs Description Type Validation eVSPriorityMailInt Required Produces a Priority Mail International label (Alias) Request with customs declaration eVSPriorityMailInt Required This attribute specifies your WebTools ID. NMTOKE Request / USERID See the Developers Guide for information on N obtaining your USERID. For example: eVSPriorityMailIntl Optional For future use. Empty Request / Option eVSPriorityMailIntl Required Use of value 2 Required as of January 2011. String Request / Revision For example: 2 eVSPriorityMailIntl Optional Groups alternate image options. (Group) minoccurs=0 Request / ImageParameters eVSPriorityMailIntl Optional, Returns alternate label image. Only alternate String Enumerations= Request / repeating 4’’x6’’ size label image may be requested at • 4X6LABEL ImageParameters up to 3 this time. • 4X6LABELL / ImageParameter times • 4X6LABEL - (4X6 on a full page 8.5/11” • 4X6LABELP background) • 4X6ZPL203DPI • 4X6LABELL - (Landscape – true size • 4X6ZPL300DPI 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) • 4X6ZPL203DPI - (ZPL - Zebra Programming Language) format. When using this enumeration, is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response. • 4X6ZPL300DPI - Prints a label formatted for ZPL printers in 300 dpi. When using this enumeration, is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response. For example: 4X6LABEL eVSPriorityMailIntl Required Both FromFirstName and FromLastName are String maxLength=30 Request / Required if FromFirmName is left blank. minLength=1 FromFirstName Maximum Length: 32 characters total for
23
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
First, Middle, and Last Names with space after first and middle name. For example: John eVSPriorityMailIntl Optional Middle Initial. Maximum Length: 32 String maxLength=1 Request / characters total for First, Middle, and Last FromMiddleInitial Names with space after first and middle name. For example: L eVSPriorityMailIntl Required Both FromFirstName and FromLastName are String maxLength=30 Request / Required if FromFirmName is left blank. minLength=1 FromLastName Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: Doe eVSPriorityMailIntl Required FromFirm is Required if FromFirstName and String maxLength=32 Request / FromLastName are left blank. FromFirm For example: XYZ eVSPriorityMailIntl Optional Use this tag for a suite or apartment number String maxLength=32 Request / only. Either Address1 or Address2 is FromAddress1 Required. For example: Suite 100 eVSPriorityMailIntl Required Use this tag for the primary address line. String maxLength=32 Request / For example: 10 Elm Street minLength=1 FromAddress2 whiteSpace=collapse eVSPriorityMailIntl Optional Use this tag for Puerto Rico only. ZIP Code String maxLength=32 Request / prefixes 006 to 009, if area is so designated. FromUrbanization For example: URB Caparra Ter eVSPriorityMailIntl Required For example: String maxLength=16 Request / Anytown minLength=1 FromCity eVSPriorityMailIntl Required Use 2-letter USPS abbreviation. String length=2 Request / For example: ST FromState eVSPriorityMailIntl Required Input tag exactly as presented, not all caps. 5 String whiteSpace=collapse Request / digits Required. length=5 FromZip5 For example: pattern=\d{5} 01234 eVSPriorityMailIntl Optional Input tag exactly as presented, not all caps. If String whiteSpace=collapse Request / value is entered, 4 digits Required. This is length=4 FromZip4 the ZIP+4 extension. pattern=\d{4} For example: 5678
24
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSPriorityMailIntl Required 10 digits Required (including area code), with String whiteSpace=collapse Request / no punctuation. Use format: 2125551234 length=10 FromPhone For example: pattern=\d{10} 5555555555 eVSPriorityMailIntl Optional Enter a value for the "Sender's Customs String maxLength=30 Request / Reference" that will appear on the label. The FromCustomsRefe text entered is any reference number that the rence sender wishes to use. For example: 45655332 eVSPriorityMailIntl Optional Deprecated. See “ToFirstName” and String maxLength=36 Request / ToName “ToLastName” tags. eVSPriorityMailIntl Required Both ToFirstName and ToLastName are String maxLength=30 Request / Required if ToFirm is left blank. ToFirstName For example: John eVSPriorityMailIntl Required Both ToFirstName and ToLastName are String maxLength=30 Request / Required if ToFirm is left blank. ToLastName For example: Doe eVSPriorityMailIntl Required ToFirm is Required if ToFirstName and String maxLength=36 Request / ToFirm ToLastName are left blank. For example: YYZ eVSPriorityMailIntl Optional Three address lines are provided, but only 1 String maxLength=36 Request / is Required. Use as many as needed for minLength=1 ToAddress1 complete address. For example: Apartado 3068 eVSPriorityMailIntl Required Three address lines are provided, but only 1 String maxLength=36 Request / is Required. Use as many as needed for ToAddress2 complete address. eVSPriorityMailIntl Optional Three address lines are provided, but only 1 String maxLength=36 Request / is Required. Use as many as needed for ToAddress3 complete address. eVSPriorityMailIntl Required Recipient's city. String maxLength=18 Request / ToCity For example: Puerto minLength=1 Vallarta eVSPriorityMailIntl Optional Enter the province for the recipient. String maxLength=9 Request / For example: ToProvince Jalisco eVSPriorityMailIntl Required The country name entered must match an String minLength=1 Request / entry from the USPS-approved International ToCountry 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.
25
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: Mexico eVSPriorityMailIntl Required Enter the postal code for the recipient. String maxLength=9 Request / For example: ToPostalCode 46807 eVSPriorityMailIntl Required Indicates whether the destination address is String Enumerations= Request / a Post Office Box. • Y ToPOBoxFlag For example: • N N eVSPriorityMailIntl Optional No format checking is done on international String maxLength=30 Request / phone numbers. Required when ToPhone Y For example: 011 52 (322) 222- 0069 eVSPriorityMailIntl Optional No format checking is done on international String maxLength=30 Request / ToFax fax numbers. For example: 011 52 (322) 222- 0074 eVSPriorityMailIntl Optional Complete valid e-mail address is Required if String maxLength=30 Request / ToEmail tag is used. whiteSpace=collapse For example: pattern=([\w\- [email protected] \.]+)@(([\w-]+\.))+[a- zA-Z]{2,4} eVSPriorityMailIntl Optional Enter a value for the "Recipient's Reference" String maxLength=28 Request / that will appear on the label. The text entered ImportersReferenc is any reference number that the recipient eNumber wishes to use. For example: Order 23432 eVSPriorityMailIntl Optional In case package is undeliverable, enter one String Enumerations= Request / of the following: • RETURN NonDeliveryOption • "RETURN" for package to be returned to • REDIRECT above. • ABANDON • "REDIRECT" to return package to address specified below in tags. • "ABANDON" to dispose of undeliverable package. For example: RETURN eVSPriorityMailIntl Optional String Minoccurs=0 Request / RedirectName eVSPriorityMailIntl Optional Enter a value for the recipient's name. String minOccurs=0 Request / RedirectName
26
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSPriorityMailIntl Optional Complete valid e-mail address is Required if String minOccurs=0 Request / tag is used. RedirectEmail eVSPriorityMailIntl Optional This value must be a syntactically-valid SMS String minOccurs=0 Request / number. RedirectSMS eVSPriorityMailIntl Optional Enter the redirect address. This is a free String minOccurs=0 Request / form field. maxLength=48 RedirectAddress eVSPriorityMailIntl Optional Redirect city. String minLength=0 Request / For example: maxLength=21 RedirectCity Anytown eVSPriorityMailIntl Optional Redirect state. String minLength=0 Request / For example: pattern=\w{2} RedirectState MN eVSPriorityMailIntl Optional Redirect ZIP code. String minLength=0 Request / For example: pattern=\d{5} RedirectZipCode 12345 eVSPriorityMailIntl Optional Redirect ZIP+4 extension. String minLength=0 Request / For example: 01234 RedirectZip4 eVSPriorityMailIntl Optional For example: String Enumerations= Request / MDFLATRATEBOX VARIABLE Container Otherwise, use to specify special containers • LGFLATRATEBO or container attributes that may affect X postage. • SMFLATRATEB OX • MDFLATRATEB OX • FLATRATEENV • LEGALFLATRAT EENV • PADDEDFLATRA TEENV • SMFLATRATEEN V • WINDOWFLATR ATEENV • GIFTCARDFLAT RATEENV • LGVIDEOBOX • RECTANGULAR • FLATRATEENV • NONRECTANGU LAR
27
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSPriorityMailIntl Required (Group) Request / ShippingContents eVSPriorityMailIntl Required Groups individual item details (Group) Request / repeating ShippingContents up to 30 / ItemDetail times eVSPriorityMailIntl Required Description of the item. String maxLength=30 Request / For example: Policy guidelines minLength=1 ShippingContents document whiteSpace=collapse / ItemDetail / Description eVSPriorityMailIntl Required Quantity of the item. Integer value Required. Integer whiteSpace=collapse Request / For example: 1 minExclusive=0 ShippingContents / ItemDetail / Quantity eVSPriorityMailIntl Required The data entered with this tag provides the Decimal whiteSpace=collapse Request / value of the set of items. minExclusive=0 ShippingContents For example: If the item is 2 boxes of 50 / ItemDetail / pens and the value of each box is $10.00, Value "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: 55.00 eVSPriorityMailIntl Required Provide the pounds component of the weight Integer default=0 Request / of the individual item listed with whiteSpace=collapse ShippingContents . / ItemDetail / For example: 1 NetPounds eVSPriorityMailIntl Required Provide the ounces component of the weight Decimal default=0.0 Request / of the individual item listed with whiteSpace=collapse ShippingContents . / ItemDetail / For example: 5 NetOunces eVSPriorityMailIntl Required For commercial items only. If known, the HS String whiteSpace=collapse Request / tariff number must be based on the maxLength=12 ShippingContents Harmonized Commodity Description and pattern=\d{0,12} / ItemDetail / Coding System developed by the World HSTariffNumber Customs Organization. For example: 490110 eVSPriorityMailIntl Required For commercial items only. Country of Origin String Request / means the country where the goods ShippingContents originated, e.g. were produced, / ItemDetail / manufactured, or assembled. CountryOfOrigin It is recommended you supply this information and attach an invoice to the
28
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
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: United States eVSPriorityMailIntl Optional Restricted use: authorized users may String Enumerations= Request / Insured indicate with a value of Y that the item is • Y insured for purposes of obtaining a barcode • N number from the insured range. All other users must specify N or omit. eVSPriorityMailIntl Optional For backward-compatibility; not validated. String Request / InsuredNumber eVSPriorityMailIntl Optional Use this tag for entering an insurance Decimal length=0 Request / amount, if known. InsuredAmount For example: 100.00 eVSPriorityMailIntl Optional Use this tag for entering a postage amount, if Decimal length=0 Request / Postage known. If the tag is present, but the value is blank, the postage will be automatically calculated. For example: eVSPriorityMailIntl Required Gross pounds and ounces together represent Integer whiteSpace=collapse Request / the total package weight, including packing GrossPounds material. For example, a package weighing 3 lbs 8 ounces would have "3" entered here and "8" entered with the tag. WebTools 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: 4 eVSPriorityMailIntl Required Enter the ounces component of the total Integer whiteSpace=collapse Request / package weight with this tag. GrossOunces For example: 0 eVSPriorityMailIntl Required Specifies the content of the package or String Enumerations= Request / envelope. • MERCHANDISE ContentType For example: • SAMPLE DOCUMENTS • DOCUMENTS
29
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
Note : “NonnegotiableDocument” and • RETURN “Documents” both signify mailable non- • HUMANITARIAN negotiable documents and are insured • DANGEROUSGO automatically for up to $100. Additional ODS Insurance cannot be purchased. Any non- • NONNEGOTIABL document values are insured EDOCUMENT automatically for up to $200. Additional • PHARMACUTICA Insurance can be purchased for values $200 LS and greater. • MEDICALSUPPLI ES • OTHER eVSPriorityMailIntl Optional Required when String maxLength=15 Request / OTHER. whiteSpace=collapse ContentTypeOther Maximum length enforced via truncation eVSPriorityMailIntl Required Requires a value of Y to print String Enumerations= Request / and in • Y Agreement Signature Box along with Current Date • N (Central Time USA). Any other value returns an error. eVSPriorityMailIntl Optional Enter any comments. String maxLength=76 Request / For example: Comments eVSPriorityMailIntl Optional Enter license number, if known or if included String maxLength=24 Request / in package. LicenseNumber For example: LIC- 24356879 eVSPriorityMailIntl Optional Enter certificate number, if known or if String maxLength=24 Request / included in package. CertificateNumber For example: CERT- 97865342 eVSPriorityMailIntl Optional Enter invoice number, if known or if included String maxLength=24 Request / in package. InvoiceNumber For example: INV- 040903 eVSPriorityMailIntl Required Label Image Type. Note: All String Enumerations= Request / values are ignored when • PDF ImageType = “4X6ZPL203DPI” or “4X6ZPL300DPI”. • TIF For example: • NONE PDF eVSPriorityMailIntl Optional Controls how the multipage form is returned String Enumerations= Request / in the response tags. "ONEPERFILE" returns • ONEPERFILE ImageLayout one page per response tag while • ALLINONEFILE “ALLINONEFILE” returns all pages in a • TRIMONEPERFI single response tag. LE The “TRIM” options conserve page space if • TRIMALLINONEF possible by combining two form parts on a ILE single page.
30
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: ONEPERFILE eVSPriorityMailIntl Optional Written to Postal Manifest Detail record. String maxLength=30 Request / For example: Ref CustomerRefNo 369246 eVSPriorityMailIntl Optional Written to Postal Manifest Detail record. String maxLength=30 Request / For example: CustomerRefNo2 ACT369246 eVSPriorityMailIntl Optional ZIP Code of Post Office or collection box String whiteSpace=collapse Request / where item is mailed. May be different than length=5 POZipCode FromZip5. This tag will take precedence over pattern=\d{5} FromZip5 when provided. For example: 00962 eVSPriorityMailIntl Optional Date the mail will enter the mail stream. No String whiteSpace=collapse Request / more than 3 days in the future. Default is day maxLength=10 LabelDate of request. pattern=\d{1,2}/\d{1,2} For example: /\d\d(\d\d)? 09/28/2010 eVSPriorityMailIntl Optional Restricted use. Holds manifest record for String Enumerations= Request / possible inclusion in SCAN request. • Y HoldForManifest • N eVSPriorityMailIntl Optional Exemption and Exclusion Legend or PFC String whiteSpace=collapse Request / Code. Use in conjunction with Revision tag minLength=0 EELPFC with value of 1 to indicate and trigger new maxLength=35 functionality. To activate check boxes use ”30.37a” or “30.37h”. For example: 30.37a Please refer to the International Mail Manual for further information http://pe.usps.gov/text/imm/immc5_007.htm. eVSPriorityMailIntl Optional Price option for package. String Enumerations= Request / • RETAIL PriceOptions • COMMERCIAL BASE • COMMERCIAL PLUS eVSPriorityMailIntl Optional Value must be numeric. Units are inches. If Decimal minExclusive=0.0 Request / Length partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this
31
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSPriorityMailIntl Optional Value must be numeric. Units are inches. If Decimal minExclusive=0.0 Request / Width partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSPriorityMailIntl Optional Value must be numeric. Units are inches. If Decimal minExclusive=0.0 Request / Height partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSPriorityMailIntl Optional Value must be numeric. Units are inches. If Decimal minExclusive=0.0 Request / Girth partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height
32
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSPriorityMailIntl Optional Groups extra services elements (Group) Request / ExtraServices eVSPriorityMailIntl Optional Parameters used to specify desired String whiteSpace=collapse Request / ExtraService. Additional occurrences for Enumerations= ExtraServices / future. • 105 ExtraService Note: The tag is used to indicate insurance. Extra Service Service Name ID e-USPS 105 Return Receipt For example: 105 eVSPriorityMailIntl Optional Used to specify the action code. Value is String Enumerations= Request / included in the Shipping Partner Event file for • M0 ActionCode customers who have chose to have a • S0 Shipping Partner Event file submitted to USPS on their behalf. M0 – Mailer Owner S0 – Service Provider For example: M0 eVSPriorityMailIntl Optional Allows a customer to opt out of SPE file Boolean Enumerations= Request / creation. “false” WILL create a SPE file. • true OptOutOfSPE Note: This request tag is case sensitive. • false eVSPriorityMailInt Optional Number associated with a mailing permit. String minOccurs=0 Request / The permit is permission to use a certain PermitNumber postage payment method for bulk and commercial mailings eVSPriorityMailInt Optional ZIP of Account Post Office where mailed if String whiteSpace=collapse Requestt / different from . Written to Postal length=5 AccountZipCode Manifest Detail record. Must be valid ZIP pattern=\d{5} Code. For example: 00962
33
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSPriorityMailInt Optional Tax code / VAT no. / Importer Code. String minOccurs=0 Request / Enumerations= ImportersReferenc • TAXCODE eType • VAT • IMPORTERCOD E eVSPriorityMailInt Optional For Importer: 10 digits (including area code), String whiteSpace=collapse Request / with no punctuation. Use format: length=10 ImportersTelephon 2125551234 pattern=\d{10} eNumber For example: 5555555555 eVSPriorityMailInt Optional For Importer: No format checking is done on String maxLength=30 Request / international fax numbers. ImportersFaxNum For example: 011 52 ber (322) 222-0074 eVSPriorityMailInt Optional For Importer: Complete valid e-mail address String maxLength=30 Request / is Required if tag is used. whiteSpace=collapse ImportersEmail For example: pattern=([\w\- [email protected] zA-Z]{2,4} eVSPriorityMailInt Optional Indicates whether or not the item is Boolean default=true Request / machinable. A surcharge is applied to a First- whiteSpace=collapse Machinable Class Mail International item if it has one or more non-machinable characteristics. See International Mail Manual (IMM) Section 241 for more information. For example: false eVSPriorityMailInt Required Required for destination entry packages. String Enumerations= Request / • I = International Service Center (ISC) • I DestinationRateIn • N = None • N dicator eVSPriorityMailInt Optional Mailer ID (MID), Represents Mail Owner String minOccurs=0 Request / MID MID. Located in position #13 in the Detail 1 record of the Shipping Services File v2.0. For example: 847654321 eVSPriorityMailInt Optional The MID of the company that manages the String minOccurs=0 Request / mailing. LogisticsManager Located in position #12 in the Detail 1 record MID of the Shipping Services File v2.0. Note: If LogisticsManagerMID is populated, either CRID or MID must also be populated. For example: 489001< / LogisticsManagerMID> eVSPriorityMailInt Optional Customer Registration ID, Represents Mail String minOccurs=0 Request / CRID Owner CRID.
34
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
Located in position #20 in the Detail 1 record of the Shipping Services File v2.0. For example: 544762 eVSPriorityMailInt Optional Code from vendor software to identify the String minOccurs=0 Request / developer of the shipping system. Default=8300 VendorCode Located in position #15 in the Detail 1 record of the Shipping Services File v2.0. For example: 1234 eVSPriorityMailInt Optional Shipping software’s product version number. String minOccurs=0 Request / Located in position #16 in the Detail 1 record VendorProductVer of the Shipping Services File v2.0. sionNumber For example: 5.02.1B eVSPriorityMailInt Optional Verifies Sender Information, sender fields String Enumerations= Request / must match From information when • 1 ePostageMailerRe =1 • 2 porting • 1 - (ePostage sender information in • 3 SSF) • 2 - (ePostage sender information through DES) • 3 - (ePostage sender information using child MID) eVSPriorityMailInt Optional First Name of Sender. String minLength=0 Request / For example: maxLength=49 SenderFirstName Adam Required when =1 eVSPriorityMailInt Optional Last Name of Sender. String minLength=0 Request / For example: maxLength=75 SenderLastName Smith Required when =1 eVSPriorityMailInt Optional Values for Sender Business Name must be String minLength=0 Request / sent. maxLength=100 SenderBusinessN For example: ame USPS eVSPriorityMailInt Optional Sender address line. Use this tag for full String minLength=0 Request / address (Address1 and Address2) maxLength=148 SenderAddress1 Must match Address1 and Address2 or will produce an error. For example: STE 150 10 Elm Street
35
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
Required when =1 eVSPriorityMailInt Optional Sender city. String minLength=0 Request / For example: maxLength=50 SenderCity BETHESDAReq uired when =1 eVSPriorityMailInt Optional Sender state. String minLength=0 Request / For example: MD Required when =1 eVSPriorityMailInt Optional Sender ZIP code. String minLength=0 Request / For example: pattern=d(5) SenderZip5 20212 Required when =1 eVSPriorityMailInt Optional Sender Phone #. 10 digits Required String minLength=0 Request / (including area code), with no punctuation. pattern=d(10) SenderPhone For example: 2125551234 Required when =1 eVSPriorityMailInt Optional E-mail Address of Sender. Valid e-mail String minLength=0 Request / addresses must be used. pattern=([\w\- SenderEmail For example: \.]+)@(([\w-]+\.)+)[a- [email protected] Required when =1 eVSPriorityMailInt Optional Used in Shipping Services File v2.0 for G-10 String 123456 Request / labels. Contact your Technical Integration (alphanumeric) ChargebackCode Specialist for details. eVSPriorityMailIntl Optional (Alias) Request 3.2.1 Sample Request Request:eVSPriorityMailInt Coins; banknotes; currency notes; securities payable to bearer; traveler's checks; gold, silver, platinum, manufactured or not; jewelry; and other valuable articles may be sent only in registered items First-Class Package International Service with Registered Mail service. Exceptions: Coins sent to or from collectors or dealers may be mailed in ordinary (uninsured) parcels. Drugs and medicines must comply with Canadian law. Eggs for hatching must be packed in new, clean containers and accompanied by a certificate issued by a veterinarian of the U.S. Department of Agriculture, or one issued by a State veterinarian and endorsed by a veterinarian of that Bureau, stating that to the best of his or her knowledge the eggs come from a flock that is free from Newcastle disease, fowl pest, or fowl typhoid. See 135.3 for method of packing. Meat and meat food products must be accompanied by an export certificate issued by the U.S. Department of Agriculture and labeled in accordance with Canadian regulations. Exception to these requirements are: 1. bona fide sample shipments weighing less than 10 kg; 2. meat products addressed to a government department or agency; 3. meat products intended for personal consumption when they enter Canada in the possession of the importer. Pet food that contains biologically appropriate raw food or bones and raw food - such as heat- processed, shelf-stable pet foods, treats, and compound chews - must be accompanied by an import permit from the Canadian Food Inspection Agency and a zoo sanitary certificate from the United States Department of Agriculture (USDA) Animal and Plant Health Inspection Service (APHIS) Veterinarian Services. Attach a copy of both documents to the outside of the mailpiece for review by the Canada Border Service Agency. Precious stones, set or not set; all items used as dress ornaments and coming under the term "jewelry" including articles of gold or other precious metal for personal use such as cigarette holders, cases, powder cases, card cases, opera glasses, fountain pens, watches, etc., are permitted in insured parcels provided the articles have value not over $5 U.S. A parcel containing a number of such articles valued at $5 or less may be insured for the total value of the contents up to a maximum of $200. Veterinary biological products including serums and vaccines must be accompanied by a permit issued by the Veterinary Director General, Ministry of Agriculture of Canada. 1. As noted in the Prohibitions section, Canada prohibits certain vaping products. However, vaping products, otherwise known as electronic smoking products (i.e., electronic products for the vaporization and administration of inhaled doses of nicotine including electronic cigarettes, cigars, cigarillos, and pipes, as well as cartridges of nicotine solutions and related products), that make health claims are subject to the Canadian Food and Drugs Act (FDA). "Health claims" refers to any statement that represents the product as a drug or device under section 2 of the FDA - for example, a statement that the product will help someone quit smoking. Vaping products that make health claims require authorization under the FDA before being commercially imported, advertised, or sold in Canada. A vaping product that makes health claims is considered a prescription drug, and before importation to Canada, it requires a Drug Establishment License and an assigned corresponding Drug Identification Number (DIN). For more information, visit canada.ca/en/health-canada/topics/licensing-authorizing-manufacturing-drug-health-products.html. Vaping products with no health claims and no drugs other than nicotine are not subject to the FDA. 2. Banknotes valued at $100 or more must be put up in a compact package and securely tied with strong twine before wrapping. The wrapper must be linen or other strong, woven material, linen lined paper, or two thicknesses of strong kraft paper. After wrapping, the package must be again securely tied or stitched and sealed at the points of closing. 3. The name of the Canadian province in which the office of destination is located must appear as part of the address. 4. The following must not be accepted for insurance: Bees, postage stamps (canceled and uncanceled) and albums in which they are mounted, and parcels addressed to CFPOs. 5. Canadian Forces Mail (CFPO) is processed through Canadian military post offices and must be addressed in the following manner: (a) NUMBER, RANK, NAME UNIT (b) CFPO (NUMBER) (c) BELLEVILLE ON K0K 3R0 (d) CANADA Maximum weight limits for mail addressed to members of the Canadian Forces based outside of Canada (CFPO) is 22 pounds. Parcels for CFPO addresses may not be insured. Direct sacks of printed matter (M-bags) are not permitted for CFPO addresses. 6. A letter fully prepaid and bearing the same address as that of a parcel may be tied or otherwise securely attached to the outside of the parcel. Stamps to cover postage on the parcel must be affixed to the wrapper of the parcel. Stamps to pay postage on the letter
41
USPS Web Tools API User Guide
must be affixed to the envelope thereof. 7. Certain types of merchandise must be marked to show country of origin in the manner prescribed by the Canadian customs regulations. 8. Goods valued under 20 Canadian dollars are duty and excise tax exempt. Goods over 20 Canadian dollars will be subject to the applicable duties and excise taxes. Gift shipments received by mail that are valued under 60 Canadian dollars are duty and excise tax exempt. 9. For all casual and commercial goods valued at or under 1,600 Canadian dollars, Canada Post will collect assessed duties, excise taxes, and a handling fee from the addressee. This handling fee is set by Canada Post (see http://www.canadapost.ca/tools/pg/manual/PGcustoms-e.asp). All commercial mail items over 1,600 Canadian dollars will be held by Canada Customs and Excise until proper invoice and accounting documentation is provided by the addressee. 10. The Canada Customs Invoice can be obtained from stationery, office supply, or printing companies. If mailers are unable to obtain the Canada Customs Invoice locally, they should visit the following Web site: www.canadapost.ca. In addition, commercial invoices are acceptable provided that each invoice has the required information for customs purposes. 11. Information on Canadian customs regulations may be obtained from the Office of International Marketing/223, Bureau of International Commerce, Department of Commerce, Washington, DC 20230, or any field office of that Department. Obtaining post code information: 12. Information on Canadian post code directories can be obtained from: (a) NATIONAL PHILATELIC CENTER CANADA POST CORPORATION STATION 1 ANTIGONISH NS B2G 2R8 Telephone: 1-800-565-4362 Fax: 1-902-863-6796 (b) To obtain Canadian post codes for specific addresses, call the General Information line at 1-416-979-8822 or access the Canada Post Corporation web site on the Internet at http://www.canadapost.ca. 13. Pursuant to the Canada Customs Act and a need to heighten border security, Canada will deny entry of all postal items (except postcards) that do not bear complete sender and addressee information in roman letters and arabic numerals. Country Code: CA Reciprocal Service Name: There is no reciprocal service. Required Customs Form/Endorsement 1. Business papers and commercial documents. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). 2. Merchandise samples and gift shipments (non-commercial parcels). PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). 3. Merchandise (commercial shipments) and all articles subject to customs duty. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Notes: 1. Gift shipments (non-commercial parcels) require a sales receipt, invoice or other documentation to support the declared value. 2. Coins; banknotes; currency notes, including paper money; securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver; precious stones; jewelry; watches; and other valuable articles are prohibited in Priority Mail Express International shipments to Canada. 3. Priority Mail Express International shipments may have a street address or a post office box address. A local telephone number for the addressee MUST be provided for shipments addressed to a post office box address. A local telephone number for the addressee should be provided if possible for shipments to a street address. Areas Served: All No Additional Restrictions Data found.0.009954 4.0 eVS First Class Mail International Label API 4.1 Overview The First Class Mail International Label API lets customers generate First Class International labels given the weight and dimensions of the item. Note: The “eVSFirstClassMailIntlCertify” API signature is for testing purposes and will not generate usable labels and barcodes.
42
USPS Web Tools API User Guide
4.1.1 API Signature Scheme Host Path API XML https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSFirstClassMailIntl &XML=(see Tag Descriptions below) https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSFirstClassMailIntl &XML=(see Tag Certify Descriptions below) 4.2 Request Descriptions
Tag Name Occurs Description Type Validation eVSFirstClassMailIntl Required (Alias) Request eVSFirstClassMailIntl Required This attribute specifies your WebTools ID. NMTOK Request / USERID See the Developers Guide for information EN on obtaining your USERID. For example: eVSFirstClassMailIntl Optional For backward compatibility; not validated. String Request / PASSWORD eVSFirstClassMailIntl Optional For future use. Empty Request / Option eVSFirstClassMailIntl Required Use of value 2 Required as of January String Request / Revision 2011. For example: 2 eVSFirstClassMailIntl Optional Groups alternate image options. (Group) minoccurs=0 Request / ImageParameters eVSFirstClassMailIntl Optional, Returns alternate label image. Only String Enumerations= Request / repeating alternate 4’’x6’’ size label image may be • 4X6LABEL ImageParameters / up to 3 requested at this time. • 4X6LABELL ImageParameter times • 4X6LABEL - (4X6 on a full page • 4X6LABELP 8.5/11” background) • 4X6ZPL203DPI • 4X6LABELL - (Landscape – true size • 4X6ZPL300DPI 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) • 4X6ZPL203DPI - (ZPL - Zebra Programming Language) format. When using this enumeration, is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response. • 4X6ZPL300DPI - Prints a label formatted for ZPL printers in 300 dpi.
43
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
When using this enumeration, is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response. For example: 4X6LABEL eVSFirstClassMailIntl Required Both FromFirstName and FromLastName String maxLength=30 Request / are Required if FromFirmName is left minLength=1 FromFirstName blank. Maximum Length: 32 characters whiteSpace=collapse total for First, Middle, and Last Names with space after first and middle name. For example: John eVSFirstClassMailIntl Optional Middle Initial. Maximum Length: 32 String maxLength=1 Request / characters total for First, Middle, and Last whiteSpace=collapse FromMiddleInitial Names with space after first and middle name. For example: L eVSFirstClassMailIntl Required Both FromFirstName and FromLastName String maxLength=30 Request / are Required if FromFirmName is left minLength=1 FromLastName blank. Maximum Length: 32 characters whiteSpace=collapse total for First, Middle, and Last Names with space after first and middle name. For example: Doe eVSFirstClassMailIntl Required FromFirm is Required if FromFirstName String maxLength=29 Request / FromFirm and FromLastName are left blank. whiteSpace=collapse For example: XYZ eVSFirstClassMailIntl Optional Use this tag for a suite or apartment String maxLength=32 Request / number only. whiteSpace=collapse FromAddress1 For example: Suite 100 eVSFirstClassMailIntl Required Use this tag for the primary address line. String maxLength=32 Request / For example: 10 Elm minLength=1 FromAddress2 Street whiteSpace=collapse eVSFirstClassMailIntl Optional Use this tag for Puerto Rico only. ZIP String maxLength=32 Request / Code prefixes 006 to 009, if area is so whiteSpace=collapse FromUrbanization designated. For example:URB Caparra Ter eVSFirstClassMailIntl Required Use this tag to specify originating city. String maxLength=16 Request / FromCity minLength=1
44
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: whiteSpace=collapse Anytown eVSFirstClassMailIntl Required Use 2-letter USPS abbreviation. String length=2 Request / FromState For example: whiteSpace=collapse AK eVSFirstClassMailIntl Required Five-digit valid ZIP code Required. String whiteSpace=collapse Request / FromZip5 For example: length=5 01234 pattern=\d{5} eVSFirstClassMailIntl Optional If value is entered, four digits are String whiteSpace=collapse Request / FromZip4 Required. Must be a valid ZIP+4 length=4 extension. pattern=\d{4} For example: 5678 eVSFirstClassMailIntl Required 10 digits Required (including area code), String whiteSpace=collapse Request / FromPhone with no punctuation. Use format: length=10 2125551234 pattern=\d{10} For example: 5555555555 eVSFirstClassMailIntl Optional Deprecated. See “ToFirstName” and String maxLength=36 Request / ToName “ToLastName” tags. eVSFirstClassMailIntl Required Both ToFirstName and ToLastName are String maxLength=30 Request / Required if ToFirm is left blank. ToFirstName For example: John eVSFirstClassMailIntl Required Both ToFirstName and ToLastName are String maxLength=30 Request / Required if ToFirm is left blank. ToLastName For example: Doe eVSFirstClassMailIntl Required ToFirm is Required if ToFirstName and String maxLength=36 Request / ToFirm ToLastName are left blank. For example: eVSFirstClassMailIntl Optional Three address lines are provided, but only String maxLength=36 Request / one is Required. Use as many as needed minLength=1 ToAddress1 for complete address. whiteSpace=collapse For example: Apartado 3068 eVSFirstClassMailIntl Required Three address lines are provided, but only String maxLength=36 Request / one is Required. Use as many as needed whiteSpace=collapse ToAddress2 for complete address. eVSFirstClassMailIntl Optional Three address lines are provided, but only String maxLength=36 Request / one is Required. Use as many as needed whiteSpace=collapse ToAddress3 for complete address. eVSFirstClassMailIntl Required Recipient's city. String maxLength=18 Request / ToCity For example: PUERTO minLength=1 VALLARTA whiteSpace=collapse eVSFirstClassMailIntl Optional Enter the province for the recipient. String maxLength=9 Request / ToProvince whiteSpace=collapse
45
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: JALISCO eVSFirstClassMailIntl Required The country name entered must match an String minLength=1 Request / ToCountry entry from the USPS-approved whiteSpace=collapse 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: MEXICO eVSFirstClassMailIntl Required Enter the postal code for the recipient. String maxLength=9 Request / For example: whiteSpace=collapse ToPostalCode 46807 eVSFirstClassMailIntl Required Indicates whether or not the To Address is String whiteSpace=collapse Request / a Post Office Box. Enumerations= ToPOBoxFlag For example: • Y N • N eVSFirstClassMailIntl Optional No format checking is done on String maxLength=30 Request / ToPhone international phone numbers. Required whiteSpace=collapse when FirstClassMailIntlRequest[ToPOBoxFlag=' Y']. For example: 011 52 (322) 222-0069 eVSFirstClassMailIntl Optional No format checking is done on String maxLength=30 Request / ToFax international fax numbers. whiteSpace=collapse For example: 011 52 (322) 222- 0074 eVSFirstClassMailIntl Optional One single, complete, and valid e-mail String maxLength=30 Request / ToEmail address is Required if tag is used. whiteSpace=collapse For example: pattern=([\w\-\.]+)@(([\w- [email protected] eVSFirstClassMailIntl Optional Used to determine the postage rate. See String whiteSpace=collapse Request / also Enumerations= FirstClassMailType FirstClassMailIntlRequest/Machinable. • PACKAGE SERVICE For example: PACKAGE SERVICE eVSFirstClassMailIntl Required (Group) Request / ShippingContents eVSFirstClassMailIntl Required (Group) Request / repeating ShippingContents / up to 5 ItemDetail times
46
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSFirstClassMailIntl Required Description of the item. Non-descriptive String maxLength=30 Request / wording such as 'Gift' will result in an minLength=1 ShippingContents / error. whiteSpace=collapse ItemDetail / For example: Policy Description guidelines document eVSFirstClassMailIntl Required Quantity of the item. Integer value Integer whiteSpace=collapse Request / Required. minExclusive=0 ShippingContents / For example: 1 maxExclusive=1000 ItemDetail / Quantity eVSFirstClassMailIntl Required The data entered with this tag provides Decimal whiteSpace=collapse Request / the value of the set of items. If the item is minExclusive=0 ShippingContents / 2 boxes of 50 pens and the value of each maxExclusive=100000 ItemDetail / Value 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: 55.00 eVSFirstClassMailIntl Required Provide the pounds component of the Integer whiteSpace=collapse Request / weight of the individual item listed within minInclusive=0 ShippingContents / this ItemDetail. ItemDetail / For example: NetPounds 1 eVSFirstClassMailIntl Required Provide the ounces component of the Decimal whiteSpace=collapse Request / weight of the individual item listed within minInclusive=0 ShippingContents / this ItemDetail. ItemDetail / For example: NetOunces 5 eVSFirstClassMailIntl Required For commercial items only. If known, the String whiteSpace=collapse Request / HS tariff number must be based on the maxLength=12 ShippingContents / Harmonized Commodity Description and minLength=0 ItemDetail / Coding System developed by the World pattern=\d{12} HSTariffNumber Customs Organization. pattern=\d{0} For example: 490110 eVSFirstClassMailIntl Required For commercial items only. Country of String whiteSpace=collapse Request / Origin means the country where the goods minLength=0 ShippingContents / originated, e.g. were produced, ItemDetail / manufactured, or assembled. It is CountryOfOrigin 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
47
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
Listings.") Using a country name not on the list will result in a request failure. For example: United States eVSFirstClassMailIntl Optional Use this tag for entering a postage String length=0 Request / Postage amount, if known. If the tag is present, but Decimal whiteSpace=collapse the value is blank, the postage will be automatically calculated. For example: eVSFirstClassMailIntl Required Gross pounds and ounces together Integer whiteSpace=collapse Request / represent the total package weight, minInclusive=0 GrossPounds 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: 4 eVSFirstClassMailIntl Required Enter the ounces component of the total Integer whiteSpace=collapse Request / package weight with this tag. minInclusive=0 GrossOunces For example: 0 eVSFirstClassMailIntl Optional Indicates whether or not the item is Boolean whiteSpace=collapse Request / Machinable machinable. A surcharge is applied to a Enumerations= First-Class Mail International item if it has • False one or more non-machinable • True characteristics. For example: false See International Mail Manual (IMM) Section 241 for more information. eVSFirstClassMailIntl Required Specifies the content of the package or String whiteSpace=collapse Request / envelope. Enumerations= ContentType For example: • MERCHANDISE DOCUMENTS • GIFT • DOCUMENTS • HUMANITARIAN • DANGEROUSGOODS • OTHER eVSFirstClassMailIntl Optional Required when String maxLength=15 Request / FirstClassMailIntlRequest[ContentType='O whiteSpace=collapse ContentTypeOther THER']. eVSFirstClassMailIntl Required Indicates the requestor's agreement to String whiteSpace=collapse Request / Agreement terms and conditions of mailing. Requires Enumerations= a value of Y to print and in Signature Box • Y
48
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
along with Current Date (Central Time USA). Any other value returns an error. eVSFirstClassMailIntl Optional For future use. String maxLength=76 Request / Comments whiteSpace=collapse eVSFirstClassMailIntl Optional For future use. String maxLength=24 Request / whiteSpace=collapse LicenseNumber eVSFirstClassMailIntl Optional For future use. String maxLength=24 Request / whiteSpace=collapse CertificateNumber eVSFirstClassMailIntl Optional For future use. String maxLength=24 Request / whiteSpace=collapse InvoiceNumber eVSFirstClassMailIntl Required Label Image Type. Note: All String whiteSpace=collapse Request / ImageType values are ignored when Enumerations= = “4X6ZPL203DPI” or • PDF “4X6ZPL300DPI”. • TIF For example: PDF eVSFirstClassMailIntl Optional Specified whether the pages are to be String whiteSpace=collapse Request / returned one per file or all in one file. The Enumerations= ImageLayout current FCMI label is one page so this tag • ONEPERFILE has no effect. • ALLINONEFILE For example: ONEPERFILE eVSFirstClassMailIntl Optional Written to Postal Manifest Detail record. String maxLength=30 Request / For example: Ref CustomerRefNo 369246 eVSFirstClassMailIntl Optional Written to Postal Manifest Detail record String maxLength=30 Request / For example: ACT CustomerRefNo2 369246 eVSFirstClassMailIntl Optional ZIP Code of Post Office or collection box String Request / POZipCode where item is mailed. May be different than FromZip5. This tag will take precedence over FromZip5 when provided. For example: 00962 eVSFirstClassMailIntl Optional Date the mail will enter the mail stream. String whiteSpace=collapse Request / LabelDate No more than three days in the future. maxLength=10 Default is day of request. pattern=\d{1,2}/\d{1,2}/\d\d(\d\ For example: d)? 09/28/2010 eVSFirstClassMailIntl Optional Restricted use. Holds manifest record for String Enumerations= Request / possible inclusion in SCAN request. • Y HoldForManifest • N
49
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSFirstClassMailIntl Optional Exemption and Exclusion Legend or PFC String whiteSpace=collapse Request / EELPFC Code. Currently Optional, in the future it minLength=0 may be Required for use. To activate maxLength=35 check boxes use ”30.37a” or “30.37h”. For example: 30.37a Please refer to the International Mail Manual for further information - http://pe.usps.gov/text/imm/immc5_007.ht m. eVSFirstClassMailIntl Optional Used to indicate package is a roll. When String Enumerations= Request / Container package is a roll, integrators should pass • ROLL = “ROLL” in XML request. If package is not a roll, integrators should not populate – label response will assume package is not a roll.
Note: When = “ROLL”, errors will return if dimensions provided in XML request do not meet IMM 251.22 requirements. https://pe.usps.com/text/imm/immc2_021. htm. eVSFirstClassMailIntl Optional Value must be numeric. Units are inches. Decimal minExclusive=0.0 Request / Length If partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSFirstClassMailIntl Optional Value must be numeric. Units are inches. Decimal minExclusive=0.0 Request / Width If partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the
50
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSFirstClassMailIntl Optional Value must be numeric. Units are inches. Decimal minExclusive=0.0 Request / Height If partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSFirstClassMailIntl Optional Value must be numeric. Units are inches. Decimal minExclusive=0.0 Request / Girth If partial dimensions are provided, an error totalDigits=10 response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSFirstClassMailIntl Optional Groups extra services elements (Group) Request / ExtraServices
51
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSFirstClassMailIntl Optional, Use to specify extra services. Currently, String Enumerations= Request / repeating available extra service is electronic USPS • 109 ExtraServices / up to 3 Delivery Confirmation International. ExtraService times Extra Service Service Name ID e-USPS Delivery 109 Confirmation International For example: 109 eVSFirstClassMailIntl Optional Indicates if retail, commercial base or String Enumerations= Request / commercial plus pricing should be • COMMERCIAL BASE PriceOptions returned. • COMMERCIAL PLUS For example: COMMERCIAL BASE eVSFirstClassMailIntl Optional Passed to SPE file via the shipment String Enumerations= Request / ActionCode manifest. • M0 • S0 eVSFirstClassMailIntl Optional Allows a customer to opt out of SPE file boolean Enumerations= Request / creation. “false” WILL create a SPE file. • True OptOutOfSPE Note: This request tag is case sensitive. • False eVSFirstClassMailInt Optional Number associated with a mailing permit. String minOccurs=0 Request / The permit is permission to use a certain PermitNumber postage payment method for bulk and commercial mailings eVSFirstClassMailInt Optional ZIP of Account Post Office where mailed if String whiteSpace=collapse Request / different from . Written to length=5 AccountZipCode Postal Manifest Detail record. Must be pattern=\d{5} valid ZIP Code. For example: 00962 eVSFirstClassMailInt Optional Indicates whether or not the item is boolean whiteSpace=collapse Request / Machinable machinable. A surcharge is applied to a First-Class Mail International item if it has one or more non-machinable characteristics. For example: false See International Mail Manual (IMM) Section 241 for more information. eVSFirstClassMailInt Required Required for destination entry packages String Enumerations= Request / • I = International Service Center • I DestinationRateIndica (ISC) • N tor • N = None
52
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSFirstClassMailInt Optional Mailer ID (MID), Represents Mail Owner String minOccurs=0 Request / MID MID. Located in position #13 in the Detail 1 record of the Shipping Services File v2.0. For example: 847654321 eVSFirstClassMailInt Optional The MID of the company that manages String minOccurs=0 Request / the mailing. LogisticsManagerMID Located in position #12 in the Detail 1 record of the Shipping Services File v2.0. Note: If LogisticsManagerMID is populated, either CRID or MID must also be populated. For example: 489001 eVSFirstClassMailInt Optional Customer Registration ID, Represents String minOccurs=0 Request / CRID Mail Owner CRID. Located in position #20 in the Detail 1 record of the Shipping Services File v2.0. For example: 544762 eVSFirstClassMailInt Optional Code from vendor software to identify the String minOccurs=0 Request / developer of the shipping system. default=8300 VendorCode Located in position #15 in the Detail 1 record of the Shipping Services File v2.0. For example: 1234 eVSFirstClassMailInt Optional Shipping software’s product version String minOccurs=0 Request / number. VendorProductVersio Located in position #16 in the Detail 1 nNumber record of the Shipping Services File v2.0. For example: 5.02.1B< / VendorProductVersionNumber> eVSFirstClassMailInt Optional Verifies Sender Information, sender fields String Enumerations= Request / must match From information when • 1 ePostageMailerRepor =1 • 2 ting • 1 - (ePostage sender information • 3 in SSF) • 2 - (ePostage sender information through DES) • 3 - (ePostage sender information using child MID) eVSFirstClassMailInt Optional First Name of Sender. String minLength=0 Request / For example: Adam Required when =1
53
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSFirstClassMailInt Optional Last Name of Sender. String minLength=0 Request / For example: Smith Required when =1 eVSFirstClassMailInt Optional Values for Sender Business Name must String minLength=0 Request / be sent. maxLength=100 SenderBusinessNam For example: e USPS eVSFirstClassMailInt Optional Sender address line. Use this tag for full String minLength=0 Request / address (Address1 and Address2) maxLength=148 SenderAddress1 Must match Address1 and Address2 or will produce an error. For example: STE 150 10 Elm Street Required when =1 eVSFirstClassMailInt Optional Sender city String minLength=0 Request / SenderCity For example: BETHESDA Required when =1 eVSFirstClassMailInt Optional Sender state. String minLength=0 Request / For example: MD Required when =1 eVSFirstClassMailInt Optional Sender ZIP code. String minLength=0 Request / SenderZip5 For example: pattern=d(5) 20212 Required when =1 eVSFirstClassMailInt Optional Sender Phone #. 10 digits Required String minLength=0 Request / (including area code), with no pattern=d(10) SenderPhone punctuation. For example: 2125551234 Required when =1 eVSFirstClassMailInt Optional E-mail Address of Sender. Valid e-mail String minLength=0 Request / addresses must be used. pattern=([\w\-\.]+)@(([\w- SenderEmail For example: ]+\.)+)[a-zA-Z]{2,4} [email protected] Required when =1 eVSFirstClassMailInt Required This contains the number of remaining String Request / barcodes that can be generated for this RemainingBarcodes particular request.
54
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSFirstClassMailInt Optional Used in Shipping Services File v2.0 for G- String 123456 (alphanumeric) Request / 10 labels. Contact your Technical ChargebackCode Integration Specialist for details. eVSFirstClassMailIntl Required (Alias) Request 4.2.1 Sample Request 24X6LABELJosephJJonesPostal ServiceSuite 101901 D Street SWWashingtonDC2002461299198887652JonJohnAustralia Zoo1638 Steve Irwin WayBeerwahQLDAUSTRALIA4519N77712345673012929999[email protected]PACKAGE SERVICECleaning Wipes11520490110UNITED STATES520false 55
Tag Name Occurs Description Type Validation eVSFirstClassMailIntlResponse Required (Alias) eVSFirstClassMailIntlResponse Required Postage amount Decimal / Postage eVSFirstClassMailIntlResponse Required Value of all items being shipped Decimal / TotalValue eVSFirstClassMailIntlResponse Required Mail service related barcode. String / BarcodeNumber eVSFirstClassMailIntlResponse Required Encoded images of label. (may be base64Binary / LabelImage empty depending upon layout selection or items shipped) eVSFirstClassMailIntlResponse Required Encoded images of label. (may be base64Binary / Page2Image empty depending upon layout selection or items shipped) eVSFirstClassMailIntlResponse Required Encoded images of label. (may be base64Binary / Page3Image empty depending upon layout selection or items shipped) eVSFirstClassMailIntlResponse Required List of items prohibited from mailing String / Prohibitions based on country of destination eVSFirstClassMailIntlResponse Required Restrictions on items being shipped String / Restrictions based on country of destination
56
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSFirstClassMailIntlResponse Required Additional mailing information based String / Observations on country of destination eVSFirstClassMailIntlResponse Required Additional regulations for shipping to String / Regulations destination country eVSFirstClassIntlResponse / Required Additional restrictions on items String AdditionalRestrictions being shipped to destination country eVSFirstClassIntlResponse / Optional String minOccurs=0 DestinationBarcodeNumber eVSFirstClassIntlResponse / Optional Appears if ExtraServices was (Group) ExtraServices populated in the request eVSFirstClassIntlResponse / Optional, Groups extra service information (Group) ExtraServices / ExtraService repeating up to unbounde d times eVSFirstClassIntlResponse / Required Extra Service ID echoed from String ExtraServices / ExtraService / request ServiceID eVSFirstClassIntlResponse / Required Extra Service name String ExtraServices / ExtraService / ServiceName eVSFirstClassIntlResponse / Required Extra Service fee Decimal ExtraServices / ExtraService/ Price eVSFirstClassMailIntlResponse Optional Echoes the RateClientType from the String / RateClientType request. If the RateClientType request is not populated on the request, this tag will not be returned. eVSFirstClassMailIntlResponse Optional String / Warning eVSFirstClassMailIntlCertifyRes Required (Alias) ponse 4.3.1 Sample Response 30.421.11LZ333007778US...... removed...... Antiquities, art fossils, historical documents, numismatic material, specimens of flora and fauna, and similar cultural heritage objects that are significant to a nation's identity. Coins; bank notes; currency notes (paper money); securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver (except for jewelry items meeting the requirement in "Restrictions" below); precious stones (except when contained in jewelry items meeting the requirement in "Restrictions" below); and other valuable articles are prohibited. Dog collars with protrusions designed to puncture or bruise an animal's skin. Fruit cartons (used or new). Fur, including raw, tanned, or processed furs or pelts, and goods that may contain such fur that are derived from
57
USPS Web Tools API User Guide
domesticated cat and dog breeds. Goods bearing the name "Anzac." Goods produced wholly or partly in prisons or by convict labor. Laser pointers and similar handheld devices designed or adapted to emit a laser beam with an accessible emission level greater than 1 megawatt (MW). Most food, plant, and animal products, including the use of products such as straw and other plant material as packing materials. Perishable infectious biological substances. Radioactive materials. Registered philatelic articles with fictitious addresses. Replica firearms, including any article that has the appearance of a firearm that could reasonably be mistaken as a firearm. Seditious literature. Signal jammers capable of preventing or disrupting mobile telephone and satellite navigation services. Silencers for firearms. Tobacco products, including cigarettes and loose-leaf tobacco. Exception: Cigars. Note: Although Australia also permits chewing tobacco and oral snuff in amounts up to 3.3 pounds (1.5 kg), the U.S. Postal Service does not permit these types of smokeless tobacco in international mail - see 136.4. Used bedding. Airsoft (BB) guns that do not have the appearance of fully automatic firearms require prior approval granted by relevant police representatives. The addressee must submit an application to import the item via the police certification test. Drugs, medicines, and therapeutic substances such as antibiotics, growth hormones, kava, psychoactive substances, and steroids require an import permit from the Australian Department of Health, Office of Drug Control. Fish or parts of fish, including all species of bony fish, sharks, rays, crustaceans, mollusks, and other marine organisms (but not including marine mammals, marine reptiles, or toothfish), whether fresh, frozen, smoked, or preserved in airtight containers, require an import permit from the Australian Fisheries Management Authority (AFMA). Jewelry is permitted only when sent as an insured parcel using Priority Mail International service. In addition, Australian Customs regulations prohibit importation of jewelry that is made with ivory or from endangered species, such as snake, elephant, or crocodile, that does not have an accompanying Import/Export Permit in relation to the Convention on International Trade in Endangered Species of Wild Fauna and Flora (CITES). Knives (such as daggers and throwing knives), throwing blades, or throwing axes require written Police Certification (B709B form or B709X form) from the Australian Police Firearms Registry. Meat and other animal products; powdered or concentrated milk; and other dairy products requires permission to import from the Australian quarantine authorities. Permission of the Australian Director- General of Health is required to import medicines. Duty may be levied on catalogs, price lists, circulars, and all advertising introduced into Australia through the mail, regardless of the class of mail used. Country Code: AU Reciprocal Service Name: Express Post Required Customs Form/Endorsement 1. Business and commercial papers. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Endorse item clearly next to mailing label as BUSINESS PAPERS. 2. Merchandise samples without commercial value microfilm, microfiche, and computer data. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). 3. Merchandise and all articles subject to customs duty. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Note: 1. Coins; banknotes; currency notes, including paper money; securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver; precious stones; jewelry; watches; and other valuable articles are prohibited in Priority Mail Express International shipments to Australia. 2. Priority Mail Express International With Guarantee service - which offers a date-certain, postage-refund guarantee - is available to Australia. Areas Served: All except Lord Howe Island and the Australian Antarctic territories. No Additional Restrictions Data found.109 Electronic USPS Delivery Confirmation International (E-USPS DELCON INTL) 0.00
58
USPS Web Tools API User Guide
9810 5.0 eVS GXG Get Label API 5.1 Overview Global Express Guaranteed is our fastest international shipping service, with transportation and delivery by FedEx Express. It features date-certain delivery in 1-3 business days* to more than 190 countries with a money-back guarantee** to all destinations. This document contains a Reference Guide to the eVS GXG Get Label Request. Please note that the GXG airway bill image is not currently supported in the response. The API returns the appropriate barcode numbers but requires the integrator to produce the GXG airway bill image. 5.1.1 API Signature Scheme Host Path API XML https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSGXGGetLabel &XML=(see Tag Descriptions below) https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSGXGGetLabel &XML=(see Tag Certify Descriptions below) 5.2 Request Descriptions
Tag Name Occurs Description Type Validation eVSGXGGetLabelRe Required (Alias) quest eVSGXGGetLabelRe Required This attribute specifies your WebTools ID. NMTOKE quest / USERID See the Developers Guide for information on N obtaining your USERID. For example: eVSGXGGetLabelRe Required For future use. Empty quest / Option eVSGXGGetLabelRe Optional This is for versioning of the APIs and for String minLength=0 quest / Revision triggering response tags for future versions. pattern=\d{1} In this API use a value of 2 to trigger new pattern= functionality. For example: 1 eVSGXGGetLabelRe Required For future use. Empty quest / ImageParameters eVSGXGGetLabelRe Required First and Last Name must be sent. Maximum String minLength=1 quest / Length: 32 characters total for First, Middle, maxLength=30 FromFirstName and Last Names with space after first and middle name. For example: John eVSGXGGetLabelRe Optional First and Last Name must be sent. Maximum String minLength=0 quest / Length: 32 characters total for First, Middle, maxLength=1 FromMiddleInitial and Last Names with space after first and middle name.
59
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: L eVSGXGGetLabelRe Required First and Last Name must be sent. Maximum String minLength=1 quest / Length: 32 characters total for First, Middle, maxLength=30 FromLastName and Last Names with space after first and middle name. For example: Doe eVSGXGGetLabelRe Required Firm Name. String minLength=0 quest / FromFirm For example: maxLength=32 USPS eVSGXGGetLabelRe Optional Secondary address unit designator and String minLength=0 quest / number (such as an apartment or suite maxLength=32 FromAddress1 number (APT 202, STE 100). For example: APT 202 eVSGXGGetLabelRe Required Street number and name (including String minLength=1 quest / predirectional, suffix, and postdirectional as maxLength=32 FromAddress2 shown in USPS ZIP+4 Product for the delivery address or rural route and box number (RR 5 BOX 10), highway contract route and box number (HC 4 BOX 45), or post office box number (PO BOX 458). For example: 10 Elm Street eVSGXGGetLabelRe Optional Urbanization name (Puerto Rico only, ZIP String minLength=0 quest / Code prefixes 006 to 009, if area is so maxLength=32 FromUrbanization designated). For example: URB Caparra Ter eVSGXGGetLabelRe Required City name. String minLength=1 quest / FromCity For example: maxLength=16 Anytown eVSGXGGetLabelRe Required Use 2-letter USPS state abbreviation. String pattern=\w\w quest / FromState For example: PA eVSGXGGetLabelRe Required Five-digit ZIP code. String pattern=\d{5} quest / FromZIP5 For example: 01234 eVSGXGGetLabelRe Optional Four-digit extension of ZIP+4 code. String minLength=0 quest / FromZIP4 For example: 5678 pattern=\d{4} pattern= eVSGXGGetLabelRe Required 10 digits Required (including area code), with String pattern=\d{10} quest / FromPhone no punctuation. Use format: 2125551234 For example: 5555555555 eVSGXGGetLabelRe Optional Origin ZIP Code shall be accepted as String minLength=0 quest / ShipFromZIP component in request via "ShipFromZip" tag.
60
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: pattern=\d{5} 18701 pattern=\d{9} pattern= eVSGXGGetLabelRe Optional E-mail address of sender. Valid e-mail String pattern=([\w\- quest / SenderEMail addresses must be used. Note: No e-mail is \.]+)@(([\w-]+\.)+)[a- returned when generating a Sample label zA-Z]{2,4} request. pattern= For example: [email protected] eVSGXGGetLabelRe Required First and Last Name must be sent. Maximum String minLength=1 quest / ToFirstName Length: 36 characters total for First, and Last maxLength=34 Names with space after first name. For example: John eVSGXGGetLabelRe Required First and Last Name must be sent. Maximum String minLength=1 quest / ToLastName Length: 36 characters total for First, and Last maxLength=34 Names with space after first name. For example: John eVSGXGGetLabelRe Required Firm Name. String minLength=0 quest / ToFirm For example: USPS maxLength=36 eVSGXGGetLabelRe Optional Three address lines are provided, but only 1 String minLength=1 quest / ToAddress1 is Required. Use as many as needed for maxLength=36 complete address. eVSGXGGetLabelRe Required Three address lines are provided, but only 1 String minLength=0 quest / ToAddress2 is Required. Use as many as needed for maxLength=36 complete address. eVSGXGGetLabelRe Optional Three address lines are provided, but only 1 String minLength=0 quest / ToAddress3 is Required. Use as many as needed for maxLength=36 complete address. eVSGXGGetLabelRe Optional Destination Postal Code. String minLength=1 quest / For example: T2G maxLength=10 ToPostalCode 2W1 eVSGXGGetLabelRe Optional Up to 25 digits allowed with no punctuation. String pattern=\d{25} quest / ToPhone For example: 1234567890 eVSGXGGetLabelRe Optional E-mail address of recipient. Valid e-mail String pattern=([\w\- quest / addresses must be used. Note: No e-mail is \.]+)@(([\w-]+\.)+)[a- RecipientEMail returned when generating a Sample label zA-Z]{2,4} request. pattern= For example: [email protected] eVSGXGGetLabelRe Required The Delivery Point ID as determined via the String pattern=\d{1,10} quest / ToDPID GXGGetDeliveryPoint API response. Please contact [email protected] for more information.
61
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: 142 eVSGXGGetLabelRe Optional Enter the province for the recipient. String minLength=0 quest / ToProvince For example: maxLength=9 JALISCO eVSGXGGetLabelRe Optional Tax ID String minLength=0 quest / ToTaxID For example: maxLength=20 eVSGXGGetLabelRe Required Container type. USPS refers to USPS- String Enumerations= quest / Container supplied large flat envelopes which incur • VARIABLE weight-based postage. • LARGEENVELO For example: PE LETTER • LETTER • LEGALENVELO PE • USPSGXGENVE LOPE • USPSGXGLEGA LENVELOPE • USPSGXGTYVE KENVELOPE • PACKAGE eVSGXGGetLabelRe Required Content type. String Enumerations= quest / ContentType For example: • DOCUMENTS DOCUMENTS eVSGXGGetLabelRe Required Contents of package. (Group) quest / ShippingContents eVSGXGGetLabelRe Required One item detail per item type enclosed. (Group) quest / repeating ShippingContents / up to 30 ItemDetail times eVSGXGGetLabelRe Required Description of the item. String minLength=1 quest / For example: Policy guidelines maxLength=35 ShippingContents / document ItemDetail / Description eVSGXGGetLabelRe Required Commodity shall be a text String matching String minLength=1 quest / Commodity Name from maxLength=100 ShippingContents / GXGGetCommodityInfo. ItemDetail / For example: Commodity Documents eVSGXGGetLabelRe Optional Allows integrators to pass restrictions (Group) quest / repeating information (responses to footnote questions) ShippingContents / up to 4 for each "Commodity/CommodityName." ItemDetail / times Restriction eVSGXGGetLabelRe Required Number associated with the commodity String maxLength=4 quest/ShippingConte restriction question returned from the Get
62
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation nts / ItemDetail / Commodity Restrictions service. Using a Restriction / number which does not pertain to the passed FootnoteNumber commodity and derived country will result in an error return. For example: 196 eVSGXGGetLabelRe Required May affect the need to use a Commercial String Enumerations= quest / invoice, and/or the ability to continue the • Y ShippingContents / transaction at all. • N ItemDetail / For example: Y Restriction / Response eVSGXGGetLabelRe Required Quantity of the item. String pattern=\d{5} quest / For example: 4 ShippingContents / ItemDetail / Quantity eVSGXGGetLabelRe Required The data entered with this tag provides the Decimal minExclusive=0.0 quest / value of the one of items in this Item Detail. ShippingContents / For example: ItemDetail / 125.00 UnitValue eVSGXGGetLabelRe Optional Rules: Integer minInclusive=0 quest /S 1. If any contains either a hippingContents / or sub-tag, then ItemDetail / all nodes must specify at least a NetPounds or tag. 2. If the and/or are specified successfully, then those values will be used in the manifesting of the Customs Declarations. 3. If and are note specified, then the value for and for each customs declaration will be the and divided by the number of present. eVSGXGGetLabelRe Optional Rules: Decimal default=0.0 quest / 1. If any contains either a minInclusive=0 ShippingContents / or sub-tag, then ItemDetail / all nodes must specify at least a NetOunces or tag. 2. If the and/or are specified successfully, then those values will be used in the manifesting of the Customs Declarations. 3. If and are note specified, then the value for and for each customs declaration will be the
63
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
and divided by the number of present. eVSGXGGetLabelRe Optional Unit of Measure for item quantity. String minLength=0 quest / For example: maxLength=20 ShippingContents / Dozen ItemDetail / UnitOfMeasure eVSGXGGetLabelRe Optional For commercial items only. If known, the HS String minLength=1 quest / tariff number must be based on the maxLength=12 ShippingContents / Harmonized Commodity Description and ItemDetail / Coding System developed by the World HSTariffNumber Customs Organization. For example: 123456 eVSGXGGetLabelRe Optional The country name entered must match an String minLength=1 quest / entry from the USPS-approved International ShippingContents / Index of Countries and Localities or be ItemDetail / "United States". Click on the link for CountryofManufactur "International Country Listings." Using a e country name not on the list will result in a request failure. Required when CIRequired=”true”. For example: United States eVSGXGGetLabelRe Required Statement of shipment purpose. String minLength=1 quest / For example: PurposeOfShipment Gift eVSGXGGetLabelRe Optional Defines relationship of parties to transaction. String Enumerations= quest / For example: • Related PartiesToTransactio Related • Other eVSGXGGetLabelRe Required Agreement to GXG service terms and String Enumerations= quest / Agreement conditions. • Y For example: Y • N eVSGXGGetLabelRe Optional Use this tag for entering the postage amount, Decimal minInclusive=0 quest / Postage if known, excluding extra services. maxInclusive=9999.9 If the value is blank, the postage will be 9 automatically calculated using retail rates. For example: 137.95 eVSGXGGetLabelRe Optional If specified, InsuredValue is used to calculate Decimal minExclusive=0.0 quest / InsuredValue the Insurance Fee. For example: 180.00 eVSGXGGetLabelRe Optional GrossPounds + (GrossOunces/16) must be Decimal maxInclusive=70 quest / GrossPounds less than 70.
64
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: 40 eVSGXGGetLabelRe Optional GrossPounds + (GrossOunces/16) must be Decimal maxInclusive=1120 quest / GrossOunces less than 70. For example: 5 eVSGXGGetLabelRe Optional Value must be numeric. Units are inches. If Decimal pattern=\d{1,2} quest / Length partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSGXGGetLabelRe Optional Value must be numeric. Units are inches. If Decimal pattern=\d{1,2} quest / Width partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSGXGGetLabelRe Optional Value must be numeric. Units are inches. If Decimal pattern=\d{1,2} quest / Height partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this
65
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSGXGGetLabelRe Optional Value must be numeric. Units are inches. If Decimal pattern=\d{1,2} quest / Girth partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non- rectangular packages.
For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm eVSGXGGetLabelRe Optional Shape, plus the package's physical String Enumerations= quest / Shape dimensions, help determine whether the • RECTANGULAR scale weight or the dimensional weight is • NONRECTANG used to calculate the shipping cost. ULAR For example: RECTANGULAR eVSGXGGetLabelRe Optional Indicates if Commercial Invoice is Required. boolean quest / CIRequired When CIRequired=” true”, commercial invoice image will be generated. For example: true eVSGXGGetLabelRe Optional Invoice date. Required when dateTime quest / InvoiceDate CommercialShipment=” true”. For example: 01/01/2012 eVSGXGGetLabelRe Optional Invoice number. Required when String minLength=1 quest / CommercialShipment=” true”. maxLength=20 InvoiceNumber For example: 20120101 eVSGXGGetLabelRe Optional Customer order number. User assigned String maxLength=20 quest / number for internal use. CustomerOrderNum For example: ber 20120101
66
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSGXGGetLabelRe Optional Customer order number. User assigned String maxLength=20 quest / number for internal use. Either use CustOrderNumber CustomerOrderNumber or CustOrderNumber. For example: 20120101 eVSGXGGetLabelRe Optional Indicates terms of delivery. Required when String Enumerations= quest / CommercialShipment=” true”. • CPT TermsDelivery For example: • CIP CPT • DAF • DDU • OTHER eVSGXGGetLabelRe Optional Terms description. Required when String minLength=1 quest / TermsDelivery=” OTHER”. maxLength=30 TermsDeliveryOther For example: DES eVSGXGGetLabelRe Optional Packing cost. Decimal minInclusive=0.00 quest / PackingCost For example: 15.00 eVSGXGGetLabelRe Required Ultimate destination country. String minLength=1 quest / For example: maxLength=38 CountryUltDest Austria eVSGXGGetLabelRe Optional Agreement to Commercial Invoice terms and boolean quest / CIAgreement conditions. Required when CIRequired=” true”. For example: true eVSGXGGetLabelRe Required Controls the file format of the commercial String Enumerations= quest / ImageType invoice image returned. • PDF For example: • TIF NONE • NONE eVSGXGGetLabelRe Optional For future use. Empty quest / ImageLayout eVSGXGGetLabelRe Optional Written to Postal Manifest Detail record. String maxLength=30 quest / For example: Ref CustomerRefNo 369246 eVSGXGGetLabelRe Optional Written to Postal Manifest Detail record. String maxLength=30 quest / For example: ACT CustomerRefNo2 369246 eVSGXGGetLabelRe Required Format: mm/dd/yyyy. No more than 4 days in String minLength=0 quest / ShipDate the future. Should "ShipDate" value not be pattern=\d{1,2}/\d{1,2 provided, the service shall use the current }/\d{4} date as a basis for delivery date pattern= calculations. For example: 01/01/2012
67
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSGXGGetLabelRe Optional Restricted use. For authorized users, holds String Enumerations= quest / manifest record for possible inclusion in • Y HoldForManifest SCAN request when Y. All other users should • N omit or specify N. For example: Y eVSGXGGetLabelRe Optional Returns commercial pricing. String minOccurs=0 quest / PriceOptions eVSGXGGetLabelRe Optional If True, then Invoice/Buyer info Required. If boolean quest / False, then Optional. CommercialShipmen For example: t true eVSGXGGetLabelRe Optional Buyer first name. Required when String minLength=1 quest / CommercialShipment=” true”. maxLength=34 BuyerFirstName For example: John eVSGXGGetLabelRe Optional Buyer last name. Required when String minLength=1 quest / CommercialShipment=” true”. maxLength=34 BuyerLastName For example: Smith eVSGXGGetLabelRe Optional Three address lines are provided, but only 1 String minLength=1 quest / is Required. Use as many as needed for maxLength=36 BuyerAddress1 complete address. Required when CommercialShipment=”true”. For example: Lazarette Str. 7 eVSGXGGetLabelRe Optional Three address lines are provided, but only 1 String minLength=1 quest / is Required. Use as many as needed for maxLength=36 BuyerAddress2 complete address. For example: eVSGXGGetLabelRe Optional Three address lines are provided, but only 1 String minLength=1 quest / is Required. Use as many as needed for maxLength=36 BuyerAddress3 complete address. For example: eVSGXGGetLabelRe Optional Buyer city. Required when String minLength=1 quest / BuyerCity CommercialShipment=” true”. maxLength=18 For example: Berlin eVSGXGGetLabelRe Optional Buyer state. Required when String minLength=1 quest / BuyerState CommercialShipment=” true”. maxLength=9 For example: eVSGXGGetLabelRe Optional Buyer postal code. Required when String minLength=1 quest / CommercialShipment=” true”. maxLength=9 BuyerPostalCode For example: 10117 eVSGXGGetLabelRe Optional Buyer country. Required when String minLength=0 quest / BuyerCountry CommercialShipment=” true”. maxLength=38
68
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation
For example: Germany eVSGXGGetLabelRe Optional Buyer TaxID. String minLength=1 quest / BuyerTaxID For example: maxLength=20 11123456789 eVSGXGGetLabelRe Optional Indicates that Buyer and Recipient are the Boolean default=true quest / same. When CommercialShipment=”true” BuyerRecipient and BuyerRecipient =”true”, buyer information is not Required. For example: true eVSGXGGetLabelRe Optional TermsPayment is Required when String minLength=1 quest / CommercialShipment =” true”. maxLength=100 TermsPayment For example: Net 50 eVSGXGGetLabelRe Optional Passed to SPE file via the shipment manifest. String Enumerations= quest / ActionCode • M0 • S0 eVSGXGGetLabelRe Optional Allows a customer to opt out of SPE file boolean Enumerations= quest / creation. “false” WILL create a SPE file. • true OptOutOfSPE Note: This request tag is case sensitive. • false eVSGXGGetLabelRe Optional Number associated with a mailing permit. String minOccurs=0 quest / The permit is permission to use a certain PermitNumber postage payment method for bulk and commercial mailings eVSGXGGetLabelRe Optional ZIP of Account Post Office where mailed if String whiteSpace=collapse quest / different from . Written to Postal length=5 AccountZipCode Manifest Detail record. Must be valid ZIP pattern=\d{5} Code. For example: 00962 eVSGXGGetLabelRe Optional Indicates whether or not the item is Boolean default=true quest / Machinable machinable. A surcharge is applied to a First- whiteSpace=collapse Class Mail International item if it has one or more non-machinable characteristics. See International Mail Manual (IMM) Section 241 for more information. For example: false eVSGXGGetLabelRe Required Required for destination entry packagesenter String Enumerations= quest / either “I” or “N”. • I DestinationRateIndic • I = International Service Center (ISC) • N ator • N = None eVSGXGGetLabelRe Optional Mailer ID (MID), Represents Mail Owner MID. String minOccurs=0 quest / MID Located in position #13 in the Detail 1 record of the Shipping Services File v2.0. For example: 847654321
69
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSGXGGetLabelRe Optional The MID of the company that manages the String minOccurs=0 quest / mailing. LogisticsManagerMI Located in position #12 in the Detail 1 record D of the Shipping Services File v2.0. Note: If LogisticsManagerMID is populated, either CRID or MID must also be populated. For example: 489001< / LogisticsManagerMID> eVSGXGGetLabelRe Optional Customer Registration ID, Represents Mail String minOccurs=0 quest / CRID Owner CRID. Located in position #20 in the Detail 1 record of the Shipping Services File v2.0. For example: 544762 eVSGXGGetLabelRe Optional Code from vendor software to identify the String minOccurs=0 quest / VendorCode developer of the shipping system. default=8300 Located in position #15 in the Detail 1 record of the Shipping Services File v2.0. For example: 1234 eVSGXGGetLabelRe Optional Shipping software’s product version number. String minOccurs=0 quest / Located in position #16 in the Detail 1 record VendorProductVersi of the Shipping Services File v2.0. onNumber For example: 5.02.1B eVSGXGGetLabelRe Optional String quest / OverrideMID eVSGXGGetLabelRe Optional Used in Shipping Services File v2.0 for G-10 String quest / labels. Contact your Technical Integration ChargebackCode Specialist for details. eVSGXGGetLabelRe Required (Alias) quest
5.2.1 Sample Request Request: eVSGXGGetLabelRequest 2JosephJJonesPostal ServiceSuite 101901 D Street SWWashingtonDC200246129 70
Tag Name Occurs Description Type Validation eVSGXGGetLabelResponse Required Public GXGGetLabel API (Alias) eVSGXGGetLabelResponse Required Postage for this package. Decimal minExclusive=0 / Postage .0 eVSGXGGetLabelResponse Required (Group) / CommodityGuarantee eVSGXGGetLabelResponse Required Guarantee date shall be provided in String Enumerations= / CommodityGuarantee / response where all commodities 'W' or 'D' • D CommodityType only. • W eVSGXGGetLabelResponse Required Where CI Required, the non-document String pattern=\d{1,2}/ / CommodityGuarantee / transit time/number of days will be used in \d{1,2}/(\d{2})?\ GuaranteeDate calculating the guarantee GXG date. d{2} eVSGXGGetLabelResponse Optional Deprecated. Decimal / Insurance eVSGXGGetLabelResponse Required USPS 10-digit human readable barcode String pattern=82\d{8} / USPSBarcodeNumber number. eVSGXGGetLabelResponse Required FedEx 12-digit human readable barcode String pattern=8982\d / FedExBarcodeNumber number. {8} eVSGXGGetLabelResponse Required For future use. Will still return an empty base64B minLength=0 / LabelImage response tag when request indicates an inary image is requested. eVSGXGGetLabelResponse Required For future use. Will still return an empty base64B minLength=0 / LabelImagePage2 response tag when request indicates an inary image is requested. eVSGXGGetLabelResponse Required For future use. Will still return an empty base64B minLength=0 / LabelImagePage3 response tag when request indicates an inary image is requested. eVSGXGGetLabelResponse Required For future use. Will still return an empty base64B minLength=0 / LabelImagePage4 response tag when request indicates an inary image is requested. eVSGXGGetLabelResponse Required When CIAgreement and CIRequired both = base64B minLength=0 / CIImage true in the request, the Commercial Invoice inary image is returned. Will still return an empty response tag when request indicates an image is requested. eVSGXGGetLabelResponse Required When CIAgreement and CIRequired both = base64B minLength=0 / CIImagePage2 true in the request, the Commercial Invoice inary image is returned. Will still return an empty response tag when request indicates an image is requested.
72
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSGXGGetLabelResponse Required When CIAgreement and CIRequired both = base64B minLength=0 / CIImagePage3 true in the request, the Commercial Invoice inary image is returned. Will still return an empty response tag when request indicates an image is requested. eVSGXGGetLabelResponse Required When CIAgreement and CIRequired both = base64B minLength=0 / CIImagePage4 true in the request, the Commercial Invoice inary image is returned. Will still return an empty response tag when request indicates an image is requested. eVSGXGGetLabelResponse Optional Insurance fee as calculated from the Decimal minExclusive=0 / InsuranceFee InsuredValue in GXGGetLabelRequest .0 eVSGXGGetLabelResponse Required String / DimensionalWeight eVSGXGGetLabelResponse Optional A text message for integrators of this API. It String / LogMessage may contain additional information about this particular request/response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis. eVSGXGGetLabelResponse Required This contains the number of remaining String / RemainingBarcodes barcodes that can be generated for this particular request. eVSGXGGetLabelResponse Required (Alias)
989 6.0 eVS International Cancel API 6.1 Overview The eVS International Cancel request allows an eVS label to be removed from processing if the request is made prior to 11:59 PM Central Time on the day of label creation.This functionality is available only if the eVS International label has been held for manifest (i.e. =”Y” is included in eVS International label XML request) and the Shipping Services File v2.0 has not yet been created. Depending on customer profile setup, this transmission could occur for created labels every 15 minutes, at the end of the shipping day, or when a SCAN Form is manually triggered by the customer. 6.1.1 API Signature Scheme Host Path API XML https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSICancel &XML=(see Tag Descriptions below) https:// secure.shippingapis.com /ShippingAPI.dll? API=eVSICancelCertify &XML=(see Tag Descriptions below) 6.2 Request Descriptions
Tag Name Occurs Description Type Validation eVSICancelRequest Required (Group) eVSICancelRequest / Required This attribute specifies your WebTools NMTOKEN USERID ID. See the Developers Guide for information on obtaining your USERID. For example: eVSICancelRequest / Required BarcodeNumber of original label. BarcodeNumber Length of 22, 30 or 34 numbers.
Tag Name Occurs Description Type Validation eVSICancelResponse Required (Alias) eVSICancelResponse / Required Returned in the eVS Label Request BarcodeNumber Length of 22, 30 or 34 numbers.
74
USPS Web Tools API User Guide
Tag Name Occurs Description Type Validation eVSICancelResponse / Required Success or Failure Indicator String “Cancelled” Status “Not Cancelled” eVSICancelResponse / Required String “Order Cancelled Reason Successfully” “Order Already Cancelled” “Order Not Found” eVSICancelResponse Required (Alias) 6.3.1 Sample Response Responses: eVSICancel 1234567890Not CancelledOrder Not Found
USPS Web Tools API User Guide 7.0 Appendix A 7.1 eVS International Label Example – Express Mail International
Figure 1: eVS Express Mail International Label Example
76
USPS Web Tools API User Guide
7.2 eVS International Label Example – Priority Mail International
Figure 2: eVS Priority Mail International Label Example
77
USPS Web Tools API User Guide
7.3 eVS International Label Example – First Class Mail International
Figure 3: eVS First Class Mail International Label Example
78
USPS Web Tools API User Guide
7.4 eVS International Label Example – GXG Get Label
Figure 4: eVS GXG International Label Example
79
USPS Web Tools API User Guide
8.0 Appendix B 8.1 Country Codes
Country Code Abu Dhabi AE Admiralty Islands (Papua New guinea) PG Afghanistan AF Aitutaki, Cook Islands (New Zealand) NZ Ajman (United Arab Emirates) AE Aland Island (Finland) FI Albania AL Alberta (Canada) CA Alderney (Channel Islands) (Great Britain and Northern Ireland) GB Algeria DZ Alhucemas (Spain) ES Alofi Island (New Caledonia) NC American Samoa, United States AS Andaman Islands (India) IN Andorra AD Angola AO Anguilla AI Anjouan (Comoros) KM Annobon Island (Equatorial Guinea) GQ Antigua (Antigua and Barbuda) AG Argentina AR Armenia AM Aruba AO Ascension SH Astypalaia (Greece) GR Atafu (Samoa) WS Atiu, Cook Islands (New Zealand) CK Australia AU Austria AT Avarua (New Zealand) NZ Azerbaijan AZ Azores (Portugal) PT Bahamas BS Bahrain BH Balearic Islands (Spain) ES Balochistan (Pakistan) PK Bangladesh BD Banks Island (Vanuatu) VU Barbados BB Barduda (Antigua and Barbuda) AG Barthelemy (Guadeloupe) BL Belarus BY
80
USPS Web Tools API User Guide
Belgium BE Belize BZ Benin BJ Bermuda BM Bhutan BT Bismark Archipelago (Papua New Guinea) PG Bolivia BO Bonaire, Sint Eustatius and Saba BQ Bora Bora (French Polynesia) PF Borneo (Indonesia) ID Botswana BW Bougainville (Papua New Guinea) PG Bourbon (Reunion) RE Brazil BR British Columbia (Canada) CA British Guiana (Guyana) GY British Virgin Islands VG Brunei Darussalam BN Buka (Papua New Guinea) PG Bulgaria BG Burkina Faso BF Burundi BI Caicos Islands(Turks and Caicos Islands) TC Cambodia KH Cameroon CM Canada CA Canary Islands (Spain) ES Canton Island (Kiribati) KI Cape Verde CV Cayman Islands KY Central African Republic CF Ceuta (Spain) ES Ceylon (Sri Lanka) LK Chad TD Chaferinas Islands (Spain) ES Chalki (Greece) GR Channel Islands (Jersey, Guemsey, Alderney and Sark) (Great JE Britain and Norther Ireland) Chile CL China CN Christmas Island (Australia) AU Christmas Island (Kiribati) KI Cocos (Keeling) Islands CC Colombia CO Comoros KM Congo, the Democratic Republic of the CD Congo CG Cook Islands CK Corisco Island (Equatorial Guinea) GQ
81
USPS Web Tools API User Guide
Corsica (France) FR Costa Rica CR Cote dIvoire CI Crete (Greece) GR Croatia HR Cuba CU Cumino Island (Malta) MT Curacao CW Cyjrenaica (Libya) LY Cyprus CY Czech Republic CZ Dahomey (Benin) BN Damao (India) IN Danger Islands (New Zealand) NZ Denmark DK Desirade Island (Guadeloupe) GP Diu (India) IN Djibouti DJ Dodecanese Islands (Greece) GR Doha (Qatar) QA Dominica DM Dominican Republic DO Dubai (United Arab Emirates) AE East Timor (Timor-Leste) TL Ecuador EC Egypt EG Eire (Ireland) IE El Salvador SV Ellice Islands (Tuvalu) TV Elobey Islands (Equatorial Guinea) GQ Enderbury Island (Kirbati) KI England (Great Britain and Northern Ireland) GB Equatorial Guinea GQ Eritrea ER Ethiopia ET Estonia EE Fakaofo (Samoa) WS Falkland Islands (Malvinas) FK Fanning Island (Kiribati) KI Faroe Islands FO Femando Po (Equatorial Guinea) GQ Fiji FJ Fezzan (Libya) LY Finland FI Fomosa (Taiwan) TW France FR French Guiana GF French Oceania (French Polynesia) PF French Polynesia PF
82
USPS Web Tools API User Guide
French West Indies (Guadeloupe) GP French West Indies (Martinique) MQ Friendly Islands (Tonga) TO Fujairah (United Arab Emirates) AE Futuna (Wallis and Futuna Islands) WF Gabon GA Gambia GM Gambier (French Polynesia) PF Georgia GE Germany DE Ghana GH Gibaltar GI Gilbert Islands (Kiribati) KI Goa (India) IN Gozo Island (Malta) MT Grand Comoro (Comoros) KM Great Britain and Northern Ireland GB Greece GR Greenland GL Grenada GD Grenadines (Saint Vincent and the Grenadines) VC Guadeloupe GP Guatemala GT Guernsey (Channel Islands) (Great Britain and GG Northern Ireland) Guinea GN Guinea–Bissau GW Guyana GY Hainan Island (China) CN Haiti HT Hashemite Kingdom (Jordan) JO Hervey, Cook Islands (New Zealand) NZ Hivaoa (French Polynesia) PF Holland (Netherlands) NL Honduras HN Hong Kong HK Huahine (French Polynesia) HM Huan Island (New Caledonia) HN Hungary HU Iceland IS India IN Indonesia ID Iran IR Irian Barat (Indonesia) ID Isle of Man IM Isle of Pines (New Caledonia) NC Isle of Pines, West Indies (Cuba) CU Israel IL Issas (Djibouti) DJ 83
USPS Web Tools API User Guide
Italy IT Ivory Coast (Cote d’Ivoire) CI Iraq IQ Jersey JE Jamaica JM Jordan JO Johore (Malaysia) MY Japan JP Kalymnos (Greece) GR Kampuchea (Cambodia) CO Karpathos (Greece) GR Kassos (Greece) GR Kazakhstan KZ Kedah (Malaysia) MY Keeling Islands (Australia) AU Kelantan (Malaysia) MY Kenya KE Kiribati KI Korea, Democratic People’s Republic of KP Korea, Republic of KR Kos (Greece) GR Kosovo, Republic of RS Kowloon (Hong Kong) HK Kuwait KW Kyrgyzstan KG Labrador (Canada) CA Laos People’s democratic Republic LA Latvia LV Labuan (Malaysia) MY Lebanon LB Leipsos (Greece) GR Leros (Greece) GR Les Saints Island (Guadeloupe) GP Liberia LR Lesotho LS Libya LY Liechtenstein LI Lithuania LT Lord Howe Island (Austrailia) AU Loyalty Islands (New Caledonia) NC Luxembourg LU Macao MO Macau (Macao) MO Macedonia, the former Yugoslav Republic of MK Madagascar MG Madeira Islands (Portugal) PT Malacca (Malaysia) MY Malawi MW Malaysia MY
84
USPS Web Tools API User Guide
Maldives MV Mali ML Malta MT Manahiki (New Zealand) NZ Manchuria (China) CN Manitoba (Canada) CA Marie Galante (Guadeloupe) GP Marquesas Islands (French Polynesia) PF Martinique MQ Mauritania MR Mauritius MU Mayotte (France) FR Melilla (Spain) ES Mexico MX Miquelon (Saint Pierre and Miquelon) PM Moheli (Comoros) KM Moldova, Republic of MD Monaco MC Mongolia MN Montenegro ME Montserrat MS Moorea (French Polynesia) PF Morocco MA Mozambique MZ Muscat (Oman) OM Myanmar (Burma) MM Namibia NA Nansil Islands (Japan) JP Nauru NR Negri Sembilan (Malaysia) MY Nepal NP Netherlands NL Nevis (Saint Kitts and Nevis) KN New Britain (Papua New guinea) PG New Brunswick (Canada) CA New Caledonia NC New Hanover (Paoua New Guinea) PG New Hebrides (Vanuatu) VU New Ireland (Papua New Guinea) PG New South Wales (Australia) AU New Zealand NZ Newfoundland (Canada) CA Nicaragua NI Niger NE Nigeria NG Nissiros (Greece) GR Niue NU Norfolk Island NF
85
USPS Web Tools API User Guide
North Borneo (Malaysia) MY North Korea KP Northern Ireland GB (Great Britain and Northern Ireland) Northwest Territory (Canada) CA Norway NO Nova Scotia (Canada) CA Nukahiva (French Polynesia) PF Nukunonu (Samoa) WS Ocean Island (Kirbati) KI Okinawa (Japan) JP Ontario (Canada) CA Oman OM Pakistan PK Palmerston, Avarua (New Zealand) NZ Panama PA Papua New Guinea PG Paraguay PY Parry, Cook Islands (New Zealand) NZ Patmos (Greece) GR Pemba (Tanzania) TZ Penang (Malaysia) MY Penghu Islands (Taiwan) TW Penon de Velez de la Gomera (Spain) ES Penrhyn, Tongareva (New Zealand) NZ Perak (Malaysia) MY Perlis (Malaysia) MY Persia (Iran) IR Peru PE Pescadores Islands (Taiwan) TW Petite Terre (Guadeloupe) GP Philippines PH Poland PL Pitcaim PN Puerto Rico PR Prince Edward Island (Canada) CA Portugal PT Pukapuka (New Zeland) NZ Qatar QA Qubec (Canada) CA Queensland (Australia) AU Quemoy (Taiwan) TW Raiatea (French Polynesia) PF Rakaanga (New Zealand) NZ Rarotonga, Cook Islands (New Zealand) NZ Ras al Kaimah (United Arab Emirates) AE Redonda (Antigua and Barbuda) AG Reunion RE Rio Muni (Equatorial Guinea) GN
86
USPS Web Tools API User Guide
Rodos (Greece) GR Rodrigues (Mauritius) MU Romania RO Rwanda RW Russian Federation RU Rwanda RW Saba (Bonaire, Sint Eustatius, and Saba) SA Sabah (Malaysia) MY Saint Barthelemy (Guadeloupe) BL Saint Bartholomew (Guadeloupe) BL Saint Helena SH Saint Kitts and Nevis KN Saint Lucia LC Saint Martin (French) (Guadeloupe) MF Saint Pierre and Miquelon PM Saint Vincent and the Grenadines VC Sainte Marie de Madagascar (Madagascar) MG Salvador (El Salvador) SV Samoa WS San Marino SM Santa Cruz Islands (Solomon Islands) SB Sao Tome and Principe ST Sarawak (Malaysia) MY Sark (Channel Islands) (Great Britain and GB Northern Ireland) Saskatchewan (Canada) CA Saudi Arabia SA Savage Island, Niue (New Zealand) NZ Savaii Island (Samoa) WS Scotland (Great Britain and Northern Ireland) GB Seberang Perai (Malaysia) MY Selangor (Malaysia) MY Senegal SN Serbia, Republic of RS Seychelles SC Sharja (United Arab Emirates) AE Shikoku (Japan) JP Sierra Leone SL Sikkim (India) IN Singapore SG Sint Eustatius (Bonaire, Sint Eustatius, and Saba) SE Solomon Islands SB Seychelles SC Sudan SD Sweden SE Singapore SG Saint Helena, Ascension and Tristan da Cunha SH Sint Maarten SX Slovakia SK
87
USPS Web Tools API User Guide
Slovenia SI Society Islands (French Polynesia) PF Solomon Islands SB Somali Democratic Republic (Somalia) SN Somalia SO Somaliland (Somalia) SO South Africa ZA South Australia (Australia) AU South Georgia (Falkland Islands) FK South Korea (Korea, Republic of) KR Spain ES Spitzbergen (Norway) NO Sri Lanka LK Sudan SD Suriname SR Suwarrow Islands (New Zealand) NZ Swan Islands (Honduras) HN Swaziland SZ Sweden SE Symi (Greece) GR Syrian Arab Republic (Syria) SY Swaziland SZ Symi (Greece) GR Syrian Arab Republic (Syria) SY Tahaa (French Polynesia) PF Tahiti (French Polynesia) PF Taiwan, Province of China TW Tajikistan TJ Tanzania TZ Tasmania (Australia) AU Tchad (Chad) TD Thailand TH Thursday Island (Australia) AU Tibet (China) CN Tilos (Greece) CR Timor (Indonesia) ID Timor-Leste, Democratic Republic of TL Trinidad and Tobago TT Togo TG Tokelau TK Tonga TO Tongareva (New Zealand) NZ Tori Shima (Japan) JP Torres Island (Vanuatu) VU Trans-Jordan, Hashemite Kingdom (Jordan) JO Transkei (South Africa) ZA Trengganu (Malaysia) MY Tripolitania (Libya) LY Tristan da Cunha TA
88
USPS Web Tools API User Guide
Trucial States (United Arab Emirates) AE Tuamotou (French Polynesia) PF Tubuai (French Polynesia) PF Tunisia TN Turkmenistan TM Turks and Caicos Islands TC Turkey TR Tuvalu TV Ukraine UA Uganda UG Umm al Quaiwain (United Arab Emirates) AE Umm Said (Qatar) QA United Arab Emirates AE United Kingdom (Great Britain and GB Northern Ireland) Upolu Island (Samoa) WS United States of America US Uruguay UY Uzbekistan UZ Vatican City VA Venezuela, Bolivarian Republic of VE Victoria (Australia) AU Viet Nam VN Virgin Islands (British) VG Wales (Great Britain and Northern Ireland) GB Vanuatu VU Wallis and Futuna WF Wellesley, Province (Malaysia) MY West New Guinea (Indonesia) PG Western Australia (Australia) AU Yemen YE Yukon Territory (Canada) CA Zafarani Islands (Spain) SB Zambia ZM Zanzibar (Tanzania) TZ Zimbabwe ZW