API

Express Mail Label

API

USPS Web ToolsTM Application Programming Interface

User's Guide

Document Version 3.5 (7/11/2017)

USPS Web Tools User's Guide

Contents

Introduction to Web Tools........................................................................................................................ 3 Before you get started: .......................................................................................................................... 3

1. USPS Priority Mail Express Label API............................................................................................ 4 1.1. Overview .................................................................................................................................... 4 1.2. API Signature ............................................................................................................................. 4

2. Tag Descriptions ............................................................................................................................... 4 2.1. Request Parameters .................................................................................................................... 4 2.1.1. Customs forms and data requirements ................................................................................. 14 2.2. Sample Request........................................................................................................................ 22 2.3. Response Parameters................................................................................................................ 25 2.4. Sample Response ..................................................................................................................... 28

3. Error Responses .............................................................................................................................. 29 4. Label Examples .............................................................................................................................. 30

4.1. Label Example with Customs Form......................................................................................... 31

ii

USPS Web Tools User's Guide

Introduction to Web Tools

This document contains a Reference Guide to the Express Mail Label APIs. See the Developer's Guide (eCommerce API Technical Guides site) to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer's Guide also contains information on testing and trouble-shooting. For label specifications such as package dimensions, delivery information, etc., please refer to the Domestic Mail Manual (DMM) at . For information specific to domestic mailpieces sent to an Army Post Office (APO), Fleet Post Office (FPOs), and or Diplomatic Post Offices (DPO) see the DMM at and 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:

12345

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

Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Technical Documentation section of the Web Tools page on webtools. Label API access requires extra permissions; contact the Internet Customer Care Center uspstechnicalsupport@mailps. to request access. Indicate "Label API Access" in the subject line and explain in the body of the email:

1. How the shipper intends to purchase and apply postage to the labels 2. If the label image provided by the API will be modified in any way by the shipper or the software

3

USPS Web Tools User's Guide

1. USPS Priority Mail Express Label API

1.1. Overview

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

1.2. API Signature

Scheme Host

Path

API

https://

secure. /ShippingAPI.dll? API=ExpressMailLabel

https://

secure. /ShippingAPI.dll? API=ExpressMailLabelCertify

XML

&XML=(see below)

&XML=(see below)

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

2. Tag Descriptions

2.1. Request Parameters

Tag Name

Occurs

Description

Type

Validation

ExpressMailLabelReq uest

required once

API=ExpressMailLabel

(group)

ExpressMailLabelReq uest / @USERID

required

NMTOKE N

ExpressMailLabelReq uest / Option

required once

For future use.

empty

In this API use a value of 2 to trigger new

ExpressMailLabelReq uest / Revision

optional

functionality.

string

For example: 2

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

ExpressMailLabelReq uest / EMCAAccount

required

For future use.

empty

ExpressMailLabelReq

uest /

required For future use.

EMCAPassword

empty

ExpressMailLabelReq

uest /

optional

ImageParameters

(group)

4

USPS Web Tools User's Guide

Tag Name

Occurs

Description

Type

ExpressMailLabelReq uest / ImageParameters / LabelSequence

Optional

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

string

ExpressMailLabelReq

uest / ImageParameters / LabelSequence

Required if...

Required if Label Sequence is selected

/PackageNumber

integer

ExpressMailLabelReq

uest / ImageParameters / LabelSequence/

Required if...

Required if Label Sequence is selected

TotalPackages

integer

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

Validation

minOccurs="0" maxOccurs="1"

minInclusive value = "1" maxInclusive value = "999"

minInclusive value = "1" maxInclusive value = "999"

ExpressMailLabelReq

uest / ImageParameters/Im

optional

ageParameter

SEPARATECONTINUEPAGE ? will force

the continuation page (if the item count

causes the need for a continuation page) string

onto a separate page.

For example: SEPARATECONTINUEPAGE

ExpressMailLabelReq required uest / FromFirstName once

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

string

Values for either First and Last Name of

Sender or Firm must be sent.

ExpressMailLabelReq required uest / FromLastName once For example:

string

MARTIAN

Values for either First and Last Name of

ExpressMailLabelReq required Sender or Firm must be sent.

uest / FromFirm

once

For example:

USPS

string

From address line 1. Use this tag for an

ExpressMailLabelReq required apartment or suite number.

uest / FromAddress1 once

For example: STE

150

string

Enumeration= SEPARATECONTINUEPAGE

minLength=0 maxLength=50

minLength=0 maxLength=50

minLength=0 maxLength=50

minLength=0 maxLength=50

5

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download