eVS Label

 

USPS Web Tools™

Application Programming Interface

Reference

Document Version 3.5 (7/31/2018)

 

 

 

 

 

 

 

 

 

 

 

United States Postal Service Logo
 


 

 

 

 

Contents

1.      Introduction.. 3

1.2    Before you get started: 3

2.      eVS Label API 4

2.1    eVS Label Request 4

2.1.1     API Signature. 4

2.1.2     eVS Request Parameters. 4

2.1.3     eVS Customs Forms and Data Requirements. 20

2.1.4     eVS Request Example. 27

2.2    eVS Label Response. 32

2.2.1     eVS Response Parameters. 32

2.2.2     eVS Response Example. 34

2.2.3     eVS Label Example – Express. 36

2.2.4     eVS Label Example – Express Customs Form.. 37

2.2.5     eVS Label Example – Priority and First Class. 38

2.2.6     eVS Label Example – Priority Customs Form.. 39

2.2.7     eVS Label Example – Library Mail 40

2.2.8     eVS Label Example – Media Mail 41

2.2.9     eVS Label Example – BPM.. 42

2.2.10   eVS Label Example – Priority Mail Cubic. 43

2.3    eVS Cancel Request 44

2.3.1   API Signature. 44

2.3.2     eVS Cancel Request Parameters. 44

2.3.3     eVS Cancel Request Examples. 44

2.3.4     eVS Cancel Response Parameters. 44

2.3.5     eVS Cancel Response Examples. 45

 

 


1. Introduction

This document contains a Reference Guide to the eVS Label API.  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 http://pe.usps.com/.

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 http://pe.usps.com/text/dmm300/703.htm#1113810 and http://pe.usps.com/text/dmm300/608.htm#1255642.

1.2           Before you get started:

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

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


 

2. eVS Label API

Note: Scan form (API=SCAN) is eligible for eVS if the HoldForManifest is Y (Yes).

2.1    eVS Label Request

The Request Parameter sections present the XML input tags for generating Live requests and the restrictions on the values allowed.  An error message will be returned if an incorrect value is entered.  Also, be aware of the maximum character amounts allowed for some tags.  If the user enters more than those amounts, an error will not be generated.  The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest.  This is important since the resulting value could prevent a correct response.

When building the XML request, pay particular attention to the order and case for tags.  An error message will be returned if an incorrect value is entered.  Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values.  For instance, a line of sample code may be:

                                        <ZipDestination>12345</ZipDestination>

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

2.1.1     API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=eVS

&XML=(see below)

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=eVSCertify

&XML=(see below)

 

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

2.1.2     eVS Request Parameters

Tag Name

Occurs

Description

Type

Validation

 

 

 

 

 

eVSRequest

required once

API=eVS

(group)

 

eVSRequest/ @USERID

required

 

NMTOKEN

 

eVSRequest/ @PASSWORD

optional

 

NMTOKEN

 

eVSRequest/ Option

optional

For future use.  

empty

 

eVSRequest/ Revision

optional

For future use.  

string

 

eVSRequest/ ImageParameters

optional

 

(group)

 

eVSRequest/ ImageParameters/ ImageParameter

optional

Returns alternate label image.

 

·     BARCODE ONLY- label option returns a barcode and Package ID Code (PIC) number without the return and delivery name and address. No label image is returned.

·     CROP - reduces the image size to half-sheet (approximately), instructions sheet will be returned, and label image will return as a landscape orientation

·     4X6LABELL- Label image will return as a Landscape – true size 4 inches vertical by 6 inches horizontal (image rotated 90 degrees from “4X6LABELP” orientation, not returned on an 8.5 x 11 background page)

·     6X4Label – Label image will be returned as traditional landscape orientation with the horizontal dimension longer than the vertical dimension (6 inches horizontal by 4 inches vertical)

·     4X6LABEL Label image will be returned as a Portrait orientation with the vertical dimension longer than the horizontal dimension (4 inches horizontal by 6 inches vertical)

·     4X6LABELP – Label image with be returned as a Portrait – true size 4 inches horizontal orientation by 6 inches vertical (not returned on an 8.5 x 11 background page)

·     SEPARATECONTINUEPAGE – will force the continuation page (if the item count causes the need for a continuation page) onto a separate page. This allows for two images to return, one label image and one continuation page.

·     4X6LABELZPL – Prints a label formatted for ZPL printers.

 

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

string

Default=4X6LABEL

 

Enumerations=

BARCODE ONLY

CROP

4X6LABEL

4X6LABELL

6X4LABEL

4X6LABELP

4X6LABELP PAGE

SEPARATECONTINUEPAGE

4X6LABELZPL

 

eVSRequest/ ImageParameters/ XCoordinate

optional

Value of the horizontal coordinate where the upper left corner of the label is placed. Combination of X and Y Coordinates will be validated to fit on the page.

 

For example:< XCoordinate>200</ XCoordinate>

integer

minValue=0  

maxValue=900

default=500 (centered)

eVSRequest/ ImageParameters/ YCoordinate

optional

Value of the vertical coordinate where the upper left corner of the label is placed. Combination of X and Y Coordinates will be validated to fit on the page.

 

For example:< YCoordinate>250</ YCoordinate>

integer

minValue=0  

maxValue=1000

default=450 (centered)

eVSRequest /  ImageParameters/  LabelSequence

optional

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

string

minOccurs="0" maxOccurs="1"

eVSRequest /  ImageParameters/  LabelSequence / PackageNumber

Required if…

Required if Label Sequence is selected

integer

minInclusive value = "1"

maxInclusive value = "999"

eVSRequest /  ImageParameters /  LabelSequence/  TotalPackages

Required if…

Required if Label Sequence is selected

integer

minInclusive value = "1"

maxInclusive value = "999"

eVSRequest/ FromName

required once

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


For example: <FromName>MT</ FromName> 

string

minLength=0  

maxLength=100

eVSRequest/ FromFirm

required once

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


For example: <FromFirm>USPS</ FromFirm> 

string

minLength=0
maxLength=50

eVSRequest/ FromAddress1

required once

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


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

string

minLength=0
maxLength=50

eVSRequest/ FromAddress2

required once

From address line 2.

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

string

minLength=1
maxLength=50

eVSRequest/ FromCity

required once

From city.


For example: <FromCity>BETHESDA</ FromCity> 

string

minLength=1
maxLength=28 

eVSRequest/ FromState

required once

From state.


For example: <FromState>MD</ FromState> 

string

minLength=2
maxLength=2  

eVSRequest/ FromZip5

required once

From ZIP code.


For example: <FromZip5>20212</FromZip5> 

string

pattern=\d{5}  

eVSRequest/ FromZip4

required once

From ZIP+4 extension.


For example: <FromZip4>2402</FromZip4> 

string

minLength=0
pattern=\d{4}

eVSRequest/ FromPhone

required once

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


For example: <FromPhone>2125551234</ FromPhone> 

string

pattern=\d{10}

eVSRequest/ POZipCode

optional

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

 

For example: <POZipCode>20770</ POZipCode>

string

minLength=0
maxLength=5 

eVSRequest/ AllowNonCleansedOriginAddr

optional

Allow Non-Cleansed Origin Address. Enter "true" if you DO NOT want the API to check the address for accuracy or "false" if the cleansing should be allowed  

 

For example:

<AllowNonCleansedOriginAddr>true

</ AllowNonCleansedOriginAddr>

boolean

default=false

 

enumeration =

true

false

 

eVSRequest/ ToName

required once

Enter a value for the recipient's name.

 

For example: <ToName>Smith</ ToName> 

string

minLength=0
maxLength=100

eVSRequest/ ToFirm

required once

Enter a value for the recipient's firm.

 

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

string

minLength=0
maxLength=50

eVSRequest/ ToAddress1

required once

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

 

For example: <ToAddress1> Suite 4D </ToAddress1> 

string

minLength=0
maxLength=50 

eVSRequest/ ToAddress2

required once

Recipient address line 2. Must be a valid address.  

 

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

string

minLength=1
maxLength=50

eVSRequest/ ToCity

required once

Recipient city.

 

For example: <ToCity>ANYTOWN</ ToCity> 

string

minLength=0
maxLength=28

eVSRequest/ ToState

required once

Recipient state.

 

For example: <ToState>MN</ ToState> 

string

minLength=0
pattern=\w{2}

eVSRequest/ ToZip5

required once

Recipient ZIP code.

 

For example: <ToZip5>12345</ ToZip5> 

string

minLength=0
pattern=\d{5}

eVSRequest/ ToZip4

required once

Recipient ZIP+4 extension.  

 

For example: <ToZip4>1844</ToZip4> 

string

minLength=0
pattern=\d{4}

eVSRequest/ ToPhone

required once

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

 

For example: <ToPhone>2125551234</ ToPhone>

string

pattern=\d{10}

eVSRequest/ POBox

optional

Indicates if destination address is a PO Box.

 

For example: <POBox>true</ POBox>

boolean

default=false

eVSRequest/ ToContactPreference

optional

This indicates how the recipient will be notified that the package is available for pickup. Specify WAIVED if notification is not desired and use tag.

 

For example: <ToContactPreference>EMAIL</ ToContactPreference>

string

whiteSpace=collapse

 

enumeration =

EMAIL

EMAILSMS

SMS

WAIVED

eVSRequest/ ToContactMessaging

optional

This contains the text messaging address or is blank depending on the ToContactPreference tag. If the EMAILSMS  or SMS enumeration is used in ToContactPreference, this value must be a syntactically-valid e-mail address. If EMAIL or WAIVED is used, this value must be blank.

 

For example: <ToContactMessaging>user@anydomain.gov</ ToContactMessaging>

string

maxLength=64

whiteSpace=collapse

pattern=\w{0}

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

eVSRequest/ ToContactEmail

optional

This contains E-mail  address or is blank depending on the ToContactPreference tag. If the EMAILSMS  or EMAIL enumeration is used in ToContactPreference, this value must be a syntactically-valid e-mail address. If SMS or WAIVED is used, this value must be blank.

Note: No e-mail is returned when  generating a Sample Label request.

 

For example:

<ToContactEMail>John.Smith@abc.com</ ToContactEMail>

string

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

eVSRequest/ AllowNonCleansedDestAddr

optional

Allow Non-Cleansed Destination Address. Enter "true" if you DO NOT want the API to check the address for accuracy or "false" if the cleansing should be allowed  

 

For example:

<AllowNonCleansedDestAddr>true</ AllowNonCleansedDestAddr>

boolean

default=false

 

enumeration=

true

false

eVSRequest/ WeightInOunces

required once

Package weight. Items must weigh 70 pounds (1120 ounces) or less. 

 

For example: <WeightInOunces>80</ WeightInOunces> 

string

pattern=\d{0,4}  

eVSRequest/ ServiceType

required once

Mail service type desired.

 

For example: <ServiceType>PRIORITY</ ServiceType>

string

enumeration =

·     PRIORITY EXPRESS

·     PRIORITY

·     FIRST CLASS

·     PARCEL SELECT GROUND

·     LIBRARY

·     MEDIA

·     BPM

·     PRIORITY MAIL CUBIC

 

 

eVSRequest/ Container

optional

Use to specify special containers or container attributes that may affect postage; otherwise leave blank. 

 

Note:  RECTANGULAR’ OR ‘NONRECTANGULAR’ required when Service Type = ‘PRIORITY’ and packaging is not USPS supplied flat or regional rate packaging.

 

For example:

<Container>FLAT RATE ENVELOPE</ Container> 

 

Note:  CUBIC PARCELS’ OR                        ‘CUBIC SOFT PACK’ required when Service Type= ‘PRIORITY MAIL CUBIC.’

 

When Container= ‘CUBIC PARCELS’, the dimensions Length, Width, and Height are required.

 

When Container= ‘CUBIC SOFT PACK,’ the dimensions Length and Height are required. The Length and Height combined may not exceed 36 inches. If a Width dimension is present, then price will automatically be calculated as a ‘CUBIC PARCEL.’

 

string

whiteSpace=collapse

 

enumeration =

·     VARIABLE

·     FLAT RATE ENVELOPE

·     LEGAL FLAT RATE ENVELOPE

·     PADDED FLAT RATE ENVELOPE

·     GIFT CARD FLAT RATE ENVELOPE

·     SM FLAT RATE ENVELOPE

·     WINDOW FLAT RATE ENVELOPE

·     SM FLAT RATE BOX

·     MD FLAT RATE BOX

·     LG FLAT RATE BOX

·     REGIONALRATEBOXA

·     REGIONALRATEBOXB

·     RECTANGULAR

·     NONRECTANGULAR

·     PACKAGE SERVICE

·     CUBIC PARCELS

·     CUBIC SOFT PACK

eVSRequest/ Width

optional

Value must be numeric. Units are inches. Required when Service Type = ‘PRIORITY’, ‘PARCEL SELECT GROUND’, ‘LIBRARY’, ‘MEDIA’, ‘BPM’

For example: <Width>5.5</ Width> 

decimal

minExclusive=0.0
totalDigits=10  

eVSRequest/ Length

optional

Value must be numeric. Units are inches. Required when Service Type = ‘PRIORITY’, ‘PARCEL SELECT GROUND’, ‘LIBRARY’, ‘MEDIA’, ‘BPM’

For example: <Length>11</ Length> 

decimal

minExclusive=0.0
totalDigits=10  

eVSRequest/ Height

optional

Value must be numeric. Units are inches. Required when Service Type = ‘PRIORITY’, ‘PARCEL SELECT GROUND’, ‘LIBRARY’, ‘MEDIA’, ‘BPM’

For example: <Height>11</ Height> 

decimal

minExclusive=0.0
totalDigits=10  

eVSRequest/ Machinable

optional

Value designates if shipment is Machinable (True), NonMachinable(False) or Irregular.

 

Irregular only applicable to <ServiceTypes> BPM, Media & Library

 

For example: <Machinable>true</ Machinable>

string

default=True

enumeration =

True  

False

Irregular

eVSRequest/ ProcessingCategory

optional

For future use.  

string

 

eVSRequest/ PriceOptions

optional

Indicates if retail or commercial pricing should be returned.

 

Required when <ServiceType> = ‘Priority Mail Cubic’

 

For example:

<PriceOptions>Commercial Base</ PriceOptions>

string

Default=Commercial Base

 

enumeration =

Retail  

Commercial Plus

Commercial Base

eVSRequest/ InsuredAmount

optional

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

 

For example:

<InsuredAmount>100.00</ InsuredAmount>

decimal

default=0

minInclusive=0 maxInclusive=9999.99

totalDigits=8

whiteSpace=collapse

eVSRequest/ AddressServiceRequested

optional

You can request the USPS to alert you when a customer changes their address. This feature is especially useful to ensure correct billing. The words “Address Service Requested” will appear on the shipping label immediately below the return address.

 

By using this tag, you will receive the following service with Priority Mail:

 

For 12 months after an address change, the mailpiece is forwarded at no charge. However, a separate notice of the new address is returned to you and an address correction fee is charged.

 

For months 13-18 after an address change, the

mailpiece is returned with the new address attached at no charge.

 

After 18 months, or if undeliverable, the mailpiece is returned with the reason for nondelivery attached at no charge.

 

Enter “True” or “False.” False is assumed if no value is entered. For fees for this service with Package Services, refer to the Domestic Mail Manual.

 

For example:

<AddressServiceRequested>true

</ AddressServiceRequested>

boolean

default=false

eVSRequest/ ExpressMailOptions

optional

Groups Express Mail Delivery and Signature options.  Valid when ServiceType=’EXPRESS’ 

(group)

 

eVSRequest/ ExpressMailOptions/ DeliveryOption

optional

Indicates desired delivery option:

 

Service Option

ServiceID

Normal Delivery (default)

1

No Weekend Delivery

2

No Holiday Delivery

3

No Weekend or Holiday Delivery

4

No Saturday Delivery

5

No Sunday Delivery

6

Sunday Delivery

7

Holiday Delivery

8

No Sunday or Holiday Delivery

9

Scheduled End of Day

E

Scheduled End of Day No Sun/ Hol Delivery

F

Scheduled End of Day No Weekend/ Hol Delivery

G

 

For example: <DeliveryOption>4</ DeliveryOption>

string

whiteSpace=collapse

default=1

enumeration =

1

2

3

4

5

6

7

8

9

E

F

G

 

eVSRequest/ ExpressMailOptions/ WaiverOfSignature

optional

No Signature Required for Delivery. Enter "True" if you do not want a signature for receipt of the package or "False" if you do.  

 

For example: <WaiverOfSignature>FALSE</WaiverOfSignature>

boolean

default=true

eVSRequest/ ShipDate

optional

Date Package Will Be Mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in either format: dd-mmm-yyyy, such as 14-Feb-2011, or mm/ dd/ yyyy, such as 02/ 14/ 2011. Should "ShipDate" value not be provided, the service shall use the
current date as a basis for delivery date calculations.
   

  

 

For example: <ShipDate>02/14/2011</ShipDate>  

string

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

eVSRequest/ CustomerRefNo

optional

User-assigned Number for Internal Use.  Up to 30 characters accepted but only 18 will be shown on the shipping label image.

 

For example:

<CustomerRefNo>XYZ #123</ CustomerRefNo>  

string

minLength=0
maxLength=30  

eVSRequest/ CustomerRefNo2

optional

User-assigned Number for Internal Use.  Up to 30 characters accepted but only 18 will be shown on the shipping label image.  Will be positioned below eVSRequest/ CustomerRefNo tag on the label image.

 

For example:

<CustomerRefNo>XYZ #123</ CustomerRefNo>  

string

minLength=0
maxLength=30  

eVSRequest/ ExtraServices

optional

Groups extra services elements

(group)

 

eVSRequest/ ExtraServices/ ExtraService

optional, repeating up to unbounded times

Use to specify extra services.  Currently available services are:

Service Name

Service ID

Insurance

100

Insurance (PME)

101

Return Receipt

102

Certified Mail

105

Return Receipt Electronic

110

Return Receipt Express Mail

118

Adult Signature

119

Adult Signature Restricted Delivery

120

Insurance (PM)

125

USPS Tracking Electronic

155

Signature Confirmation Electronic

156

10:30 AM Delivery (PME)

161

Certified Mail Restricted Delivery

170

Certified Mail Adult Signature Required

171

Certified Mail Adult Signature Restricted Delivery

172

Signature Confirmation Electronic Restricted Delivery

174

Insurance Restricted Delivery

177

Insurance Restricted Delivery (PME)

178

Insurance Restricted Delivery (PM)

179

Special Handling - Fragile

190

string

whiteSpace=collapse

 

enumeration =

100

101

102

105

110

118

119

120

125

155

156

161

170

171

172

174

177

178

179

190

 

 

 

 

 

eVSRequest/ HoldForPickup

optional

For future use.  

(group)

 

eVSRequest/ OpenDistribute

optional

For future use.  

(group)

 

eVSRequest/ PermitNumber

optional

For future use.  

string

 

eVSRequest/ PermitZIPCode

optional

For future use.  

string

 

eVSRequest/ PermitHolderName

optional

For future use.  

string

 

eVSRequest/ CRID

optional

Customer Registration ID, Represents Mail Owner CRID.

 

For example: <CRID>544762</ CRID>

string

minLength=0
maxLength=15

eVSRequest/ MID

optional

Mailer ID (MID), Represents Mail Owner MID.

 

For example: <MID>847654321</ MID>

string

Length=6 or 9 positions if populated

eVSRequest/ LogisticsManagerMID

optional

The MID of the company that manages the mailing.

Note: If LogisticsManagerMID is populated, either CRID or MID must also be populated.

 

For example: < LogisticsManagerMID>489001< / LogisticsManagerMID>

string

Length=6 or 9 positions if populated

eVSRequest/ VendorCode

optional

Code from vendor software to identify the developer of the shipping system.

 

For example: < VendorCode>1234<VendorCode>

string

minLength=0
maxLength=4

default=8300

eVSRequest/ VendorProductVersionNumber

optional

Shipping software’s product version number.

 

For example: <VendorProductVersionNumber>5.02.1B</  VendorProductVersionNumber>

string

minLength=0
maxLength=8

eVSRequest/ SenderName

optional

Name of E-mail Sender.  

 

For example:

<SenderName>Adam Smith</ SenderName>  

string

minLength=0

maxLength=50 

eVSRequest/ SenderEMail

optional

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

 

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

string

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

eVSRequest/ RecipientName

optional

Name of E-mail Recipient  

 

For example: <RecipientName>Mike Smith</RecipientName > 

string

minLength=0

maxLength=50 

eVSRequest/ RecipientEMail

optional

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

 

For example: <RecipientEMail>msmith@email.com</ RecipientEMail> 

string

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

eVSRequest/ ReceiptOption

optional

Label & Receipt print layout options. Enter "SEPARATE PAGE" if you want the shipping label and online customer record printed on two separate pages, "SAME PAGE" if you want them printed on the same single page, or “NONE” if no receipt is requested.

 

For example:

<ReceiptOption>SAME PAGE</ ReceiptOption>

string

default=SAME PAGE

enumeration =

SEPARATE PAGE
NONE  

eVSRequest/ ImageType

required once

Label Image Type.  

 

For example: <ImageType>PDF</ ImageType>

string

 

enumeration =

PDF
TIF
None  

eVSRequest/ HoldForManifest

optional

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

string

enumeration =

Y
N

eVSRequest/ NineDigitRoutingZip

optional

Indicates if nine digit routing zip code is included in the barcode.

 

For example:

<NineDigitRoutingZip>false</ NineDigitRoutingZip>

boolean

default=false 

eVSRequest/ ShipInfo

optional

Indicates if revenue protection information is printed on the label.

 

For example:

<ShipInfo>false</ ShipInfo>

boolean

default=false 

eVSRequest/

CarrierRelease

optional

Indicates if the ‘CARRIER – LEAVE IF NO RESPONSE’ is to be printed on the label. This endorsement cannot be applied to Express Mail or items requiring a signature at delivery (e.g. Signature Confirmation, Insurance > $500).

 

For example:

<CarrierRelease>false</ CarrierRelease>

boolean

default=false 

eVSRequest/

DropOffTime

optional

Indicates the time the package will be dropped off.

Time is specified in military time.

 

For example:

<DropOffTime>13:00</ DropOffTime>

boolean

default=label creation time

eVSRequest/

ReturnCommitments

optional

Indicates that the CommitmentName and Scheduled DeliveryDate will be returned in the response.

 

For example:

<ReturnCommitments>false</ ReturnCommitments>

boolean

default=false

eVSRequest/

PrintCustomerRefNo

optional

Print <CustomerRefNo> in the additional information section.

boolean

default=false

eVSRequest/

Content

optional

Groups Content

(group)

 

eVSRequest/

Content/ ContentType

required once

Use to specify ContentType.  Currently available types are:

 

ContentType

HAZMAT

CrematedRemains

Lives

Perishable

Pharmaceuticals

MedicalSupplies

 

For example: < ContentType >Lives</  ContentType >

string

enumeration =

HAZMAT 

CrematedRemains

Lives

Perishable

Pharmaceuticals

MedicalSupplies

eVSRequest/

Content/ ContentDescription

optional – max one occurrence

Use to specify Content Description. Required when <ContentType>Lives</ ContentType> is supplied. Valid Values

 

ContentDescription

Bees

DayOldPoultry

AdultBirds

Other

 

 

For example: < ContentDescription >DayOldPoultry </ ContentDescription >

String

enumeration =

 Bees 

 DayOldPoultry

 AdultBirds

 Other

eVSRequest/ActionCode

optional

Used to specify the action code.

 

For example: <ActionCode>M0</ActionCode>

String

Default = M0

 

enumeration=

    M0 – Mailer Owner

    S0 – Service Provider

  

eVSRequest/ OptOutOfSPE

optional

Used to specify if a SPE file will be created.

 

For example: < OptOutOfSPE > false </ OptOutOfSPE >

boolean

default=true

eVSRequest/

SortationLevel

optional

Use to specify Sortation Level. Needed if non-machinable.

 

For example: < SortationLevel>MIX</ SortationLevel>

String

 

eVSRequest/

DestinationEntryFacilityType

optional

Use to specify Destination Entry Facility Type.

 

For example: <DestinationEntryFacilityType>DNDC</  DestinationEntryFacilityType

String

enumeration =

None (default)

DNDC

DSCF

DDU

 

2.1.3     eVS Customs Forms and Data Requirements

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

Please see the below “CustomsContentType” tag for specific customs forms and data requirements and logic.

Tag Name

Occurs

Description

Type

Validation

eVSRequest / ShippingContents

required once or optional

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

 

(group)

eVSRequest / ShippingContents / ItemDetail

required once repeating up to 30 times or optional

required once repeating up to 30 times if generating an Integrated Customs Form, otherwise not required

 

(group)

eVSRequest / ShippingContents / ItemDetail /Description

Optional/required

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

 

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

string

minLength=1

maxLength=30

eVSRequest / ShippingContents / ItemDetail /Quantity

Optional/required

Quantity of the item. Integer value required. Required only if a customs form is required based on Customs Content Type and Weight.

 

For example: <Quantity>1</Quantity>

integer

whitespace=collapse

maxInclusive  value=9999

eVSRequest / ShippingContents / ItemDetail / Value

Optional/required

The data entered with this tag provides the value of the set of items. If the item is 2 boxes of 50 pens and the value of each box is $10.00, "20.00" (2 boxes x $10.00) should be entered. If the value of each pen is .25 then "25.00" (100 pens x .25) should be entered. Required only if a customs form is required based on Customs Content Type and Weight.

 

For example: <Value>55.00</Value>

decimal

minExclusive value=0                                                  totalDigits value=8                                                  maxInclusive  value=99999.99

eVSRequest / ShippingContents / ItemDetail / NetPounds

optional/required

Provide the pounds OR ounces component of the weight of the individual item listed with <Description> when a customs form is required based on Customs Content Type and Weight.

 

For example: <NetPounds>1</NetPounds>

integer

totalDigits value=2                                                  minInclusive value=0                                         maxInclusive value=70

eVSRequest / ShippingContents / ItemDetail / NetOunces

optional/required

Provide the ounces OR pounds component of the weight of the individual item listed with <Description> when a customs form is required based on Customs Content Type and Weight.

 

For example: <NetOunces>5</NetOunces>

decimal

totalDigits value=5                                                 minInclusive value=0                                       maxInclusive value=1120

eVSRequest / ShippingContents / ItemDetail / HSTariffNumber

optional

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

 

For example: <HSTariffNumber>490110</HSTariffNumber>

string

minLength=0

maxLength=12

eVSRequest / ShippingContents / ItemDetail / CountryofOrigin

optional

Country of Origin means the country where the goods originated, e.g. were produced, manufactured, or assembled. It is recommended you supply this information and attach an invoice to the outside to accelerate customs clearance in processing the items. The country name entered must match an entry from the USPS-approved International Index of Countries (see http://pe.usps.com/text/imm/immctry.htm) and Localities or be "United States".

 

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

string

minLength=0

maxLength=100

eVSRequest / CustomsContentType

Required

Specifies the content of the package or envelope.

For example: <CustomsContentType>DOCUMENTS</CustomsContentType>

When sending TO or FROM an APO/FPO/DPO or PTFAS, additional Customs information is required.  This requirement is triggered when

·       The “eVSRequest/ ToState” is an APO/FPO/DPO or PTFAS

·       The “eVSRequest/POZipCode” is specified and is an APO/FPO/DPO or PTFAS

·       The “eVSRequest/POZipCode” is NOT specified and The “eVSRequest/ FromState” is an APO/FPO/DPO or PTFAS

 

When one of the above conditions occurs, The Customs Content Type tag is required.  If the Content Type is “DOCUMENTS” and the “WeightInOunces” is specified and is less than 16 oz. no additional Customs tags are required from this section (2.1.3).

 

More information can be found in the DMM at:http://pe.usps.com/text/dmm300/608.htm#1255642

string

minOccurs=0

 

enumeration=

MERCHANDISE

GIFT

DOCUMENTS

SAMPLE

RETURN

OTHER

HUMANITARIAN

DANGEROUSGOODS

eVSRequest / ContentComments

optional

Required tag if <CustomsContentType> =Other

 

Enter any comments. For example: <ContentComments>Parts</ContentComments>

string

minOccurs=0

maxLength=25

eVSRequest / RestrictionType

optional

Restriction Types

string

minOccurs=0

 

Enumeration=

Quarantine

Sanitary Inspection

Phytosanitary Inspection

Other

eVSRequest / RestrictionComments

optional

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

string

minOccurs=0

eVSRequest / AESITN

optional

AES/ITN Exemption is a code that indicates the reason why you did not need to file electronic export information

string

minOccurs=0

eVSRequest / ImportersReference

optional

Use tag when ServiceType is equal to Priority

 

Importers Reference.  The Importer’s Reference might be a tax code, importer code, or VAT number used for sales tax

string

minOccurs=0

eVSRequest / ImportersContact

optional

Use tag  when ServiceType is equal to Priority

 

Importers Contact.  Enter, if known, the Importer’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery.

string

minOccurs=0

eVSRequest / ExportersReference

optional

Use tag when ServiceType is equal to Priority

 

Exporters Reference.  The Exporter’s Reference might be a tax code, importer code, or VAT number used for sales tax

string

minOccurs=0

eVSRequest / ExportersContact

optional

Use tag when ServiceType is equal to Priority

 

Exporters Contact.  Enter, if known, the Exporter’s telephone number, fax number, or email address, as such information might facilitate customs clearance or delivery.

string

minOccurs=0

eVSRequest / InvoiceNumber

optional

Use tag when ServiceType is equal to Priority

 

Invoice Number

string

minOccurs=0

eVSRequest / LicenseNumber

optional

Use tag when ServiceType is equal to Priority

 

License Number

string

minOccurs=0

eVSRequest / CertificateNumber

optional

Use tag – when ServiceType is equal to Priority

 

Certificate Number

string

minOccurs=0

eVSRequest / NonDeliveryOption

optional

In case package is undeliverable, enter one of the following: "RETURN" for package to be returned to <FromAddress> above. "REDIRECT" to return package to address specified in the below tags. "ABANDON" to dispose of undeliverable package.

 

For example: <NonDeliveryOption>RETURN</NonDeliveryOption>

string

enumeration=RETURN
enumeration=REDIRECT
enumeration=ABANDON

eVSRequest / AltReturnAddress1

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is for an apartment or suite number.  

 

For example: <AltReturnAddress1>Apt 1</AltReturnAddress1>

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

eVSRequest / AltReturnAddress2

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the Recipient address line 2. Must be a valid address.  

 

For example: <AltReturnAddress2>123 Main Ave </ AltReturnAddress2>

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

eVSRequest / AltReturnAddress3

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the Recipient city.

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

eVSRequest / AltReturnAddress4

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the Recipient state. Use 2-letter USPS abbreviation.

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

eVSRequest / AltReturnAddress5

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the recipient ZIP code.

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

eVSRequest / AltReturnAddress6

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Suggested use of this tag is the recipient ZIP+4 extension  

 

Note:

1. Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

 

2. Requirement ignored when <Container> specified is a flat rate envelope or small flat rate box variation.

string

minOccurs=0

eVSRequest / AltReturnCountry

optional

Required if NonDeliveryOption tag=REDIRECT.

 

Country.  Tag must equal United States for this API.

string

minOccurs=0

eVSRequest/

LabelImportType

optional

“for Internal USPS use only”

string

 

eVSRequest/

ePostageMailerReporting

optional

Verifies Sender Information, sender fields must match From information when <ePostageMailerReporting>=1

string

Enumerations=

1 - (ePostage sender information in SSF )

 2 -  (ePostage sender information through DES)

 3 - (ePostage sender information using child MID)

eVSRequest/SenderFirstName

optional

First Name of Sender.  

 For example:

<SenderFirstName>Adam </ SenderFirstName>  

 Required when <ePostageMailerReporting>=1

string

minLength=0, maxLength=49

 

eVSRequest/SenderLastName

optional

Last Name of Sender.  

For example:

<SenderLastName>Smith </ SenderLastName>  

 Required when <ePostageMailerReporting>=1

string

minLength=0, maxLength=75

eVSRequest/SenderBusinessName

optional

Values for Sender Business Name must be sent.

For example: <SenderBusinessName>USPS</ SenderBusinessName> 

string

minLength=0, maxLength=100

eVSRequest/SenderAddress1

optional

Sender address line 1. Use this tag for full Sender’s Address.

 

For example: <SenderAddress1>123 Fake ST STE 150</ SenderAddress1> 

 

Required when <ePostageMailerReporting>=1

string

minLength=0, maxLength=148

eVSRequest/SenderCity

optional

Sender city.


For example: <SenderCity>BETHESDA</ SenderCity> Required when <ePostageMailerReporting>=1

string

minLength=0, maxLength=50

eVSRequest/SenderState

optional

Sender state.


For example: <SenderState>MD</ SenderState> Required when <ePostageMailerReporting>=1

 

string

minLength=0, maxLength=2

eVSRequest/SenderZip5

optional

Sender ZIP code.


For example: <SenderZip5>20212</SenderZip5> 

Required when <ePostageMailerReporting>=1

string

minLength=0, pattern=d[5]

eVSRequest/SenderPhone

optional

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


For example: <SenderPhone>2125551234</ SenderPhone> 

Required when <ePostageMailerReporting>=1

string

minLength=0, pattern=d[10]

eVSRequest/SenderEmail

optional

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

 

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

Required when <ePostageMailerReporting>=1

string

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

eVSRequest Request

required once

 

(alias)

 

 

2.1.4       eVS Request Example

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

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

<eVSCertifyRequest  mlns:xsi="http:/ / www.w3.org/ 2001/ XMLSchema-instance" USERID="XXXXXX">

    <Option>1</ Option>

  <Revision></ Revision>

  <ImageParameters>

    <LabelSequence>

      <PackageNumber>2</ PackageNumber>

      <TotalPackages>3</ TotalPackages>

    </ LabelSequence>

  </ ImageParameters>

  <FromName>Joe Smith</ FromName>

  <FromFirm>ABC Corp.</ FromFirm>

  <FromAddress1>Apt. 3C</ FromAddress1>

  <FromAddress2>6406 Ivy Lane</ FromAddress2>

  <FromCity>Greenbelt</ FromCity>

  <FromState>MD</ FromState>

  <FromZip5>20770</ FromZip5>

  <FromZip4>1234</ FromZip4>

  <FromPhone>5708208072</ FromPhone>

  <POZipCode></ POZipCode>

  <AllowNonCleansedOriginAddr>false</ AllowNonCleansedOriginAddr>

  <ToName>Tom Collins</ ToName>

  <ToFirm>XYZ Corp.</ ToFirm>

  <ToAddress1>Suite 4D</ ToAddress1>

  <ToAddress2>8 Wildwood Drive</ ToAddress2>

  <ToCity>Old Lyme</ ToCity>

  <ToState>CT</ ToState>

  <ToZip5>06371</ ToZip5>

  <ToZip4></ ToZip4>

  <ToPhone></ ToPhone>

  <POBox></ POBox>

  <AllowNonCleansedDestAddr></ AllowNonCleansedDestAddr>

  <WeightInOunces>32</ WeightInOunces>

  <ServiceType>Express</ ServiceType>

  <Container>FLAT RATE ENVELOPE</ Container>

  <Width></ Width>

  <Length></ Length>

  <Height></ Height>

  <Machinable></ Machinable>

  <ProcessingCategory></ ProcessingCategory>

  <PriceOptions></ PriceOptions>

  <InsuredAmount></ InsuredAmount>

  <AddressServiceRequested></ AddressServiceRequested>

  <ExpressMailOptions>

    <DeliveryOption></ DeliveryOption>

    <WaiverOfSignature></ WaiverOfSignature>

  </ ExpressMailOptions>

  <ShipDate></ ShipDate>

  <CustomerRefNo></ CustomerRefNo>

  <ExtraServices>

    <ExtraService></ ExtraService>

  </ ExtraServices>

  <HoldForPickup></ HoldForPickup>

  <OpenDistribute></ OpenDistribute>

  <PermitNumber></ PermitNumber>

  <PermitZIPCode></ PermitZIPCode>

  <PermitHolderName></ PermitHolderName>

  <CRID></ CRID>

  <SenderName></ SenderName>

  <SenderEMail></ SenderEMail>

  <RecipientName>Joseph Smoth</ RecipientName>

  <RecipientEMail>jsmith1234@aol.com</ RecipientEMail>

  <ReceiptOption></ ReceiptOption>

  <ImageType>TIF</ ImageType>

  <HoldForManifest></ HoldForManifest>

  <NineDigitRoutingZip></ NineDigitRoutingZip>

  </ eVSCertifyRequest> 

 

 

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

<?xml version="1.0" encoding="UTF-8" ?><eVSCertifyRequest  mlns:xsi="http:/ / www.w3.org/ 2001/ XMLSchema-instance" USERID="XXXXXX">

    <Option>1</ Option>

  <Revision></ Revision>

  <ImageParameters>

    <LabelSequence>

      <PackageNumber>2</ PackageNumber>

      <TotalPackages>3</ TotalPackages>

    </ LabelSequence>

  </ ImageParameters>

  <FromName>Joe Smith</ FromName>

  <FromFirm>ABC Corp.</ FromFirm>

  <FromAddress1>Apt. 3C</ FromAddress1>

  <FromAddress2>6406 Ivy Lane</ FromAddress2>

  <FromCity>Greenbelt</ FromCity>

  <FromState>MD</ FromState>

  <FromZip5>20770</ FromZip5>

  <FromZip4>1234</ FromZip4>

  <FromPhone>5708208072</ FromPhone>

  <POZipCode></ POZipCode>

  <AllowNonCleansedOriginAddr>false</ AllowNonCleansedOriginAddr>

  <ToName>Tom Collins</ ToName>

  <ToFirm>XYZ Corp.</ ToFirm>

  <ToAddress1>Suite 4D</ ToAddress1>

  <ToAddress2>8 Wildwood Drive</ ToAddress2>

  <ToCity>Old Lyme</ ToCity>

  <ToState>CT</ ToState>

  <ToZip5>06371</ ToZip5>

 <ToZip4></ ToZip4>

  <ToPhone></ ToPhone>

<POBox></POBox>

  <AllowNonCleansedDestAddr></AllowNonCleansedDestAddr>

  <WeightInOunces>12</WeightInOunces>

  <ServiceType>priority</ServiceType>

  <Container>Rectangular</Container>

  <Width>1</Width>

  <Length>1</Length>

  <Height>1</Height>

  <Machinable></Machinable>

  <ProcessingCategory></ProcessingCategory>

  <PriceOptions></PriceOptions>

  <InsuredAmount>1000</InsuredAmount>

  <AddressServiceRequested>true</AddressServiceRequested>

  <ExpressMailOptions>

    <DeliveryOption></DeliveryOption>

    <WaiverOfSignature></WaiverOfSignature>

  </ExpressMailOptions>

  <ShipDate></ShipDate>

  <CustomerRefNo></CustomerRefNo>

  <ExtraServices>

    <ExtraService></ExtraService>

  </ExtraServices>

  <HoldForPickup></HoldForPickup>

  <OpenDistribute></OpenDistribute>

  <PermitNumber></PermitNumber>

  <PermitZIPCode></PermitZIPCode>

  <PermitHolderName></PermitHolderName>

  <CRID></CRID>

  <SenderName></SenderName>

  <SenderEMail></SenderEMail>

  <RecipientName>Robert Meier</RecipientName>

  <RecipientEMail></RecipientEMail>

  <ReceiptOption></ReceiptOption>

  <ImageType>TIF</ImageType>

  <HoldForManifest></HoldForManifest>

  <NineDigitRoutingZip></NineDigitRoutingZip>

  <ShipInfo>true</ShipInfo>

  <CarrierRelease></CarrierRelease>

  <ReturnCommitments>true</ReturnCommitments>

  <PrintCustomerRefNo></PrintCustomerRefNo>

  <Content>

    <ContentType></ContentType>

    <ContentDescription></ContentDescription>

  </Content>

<ShippingContents>

    <ItemDetail>

      <Description>Description 1</Description>

      <Quantity>9999</Quantity>

      <Value>1.11</Value>

      <NetPounds></NetPounds>

      <NetOunces>1</NetOunces>

      <HSTariffNumber>123456789012</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 2</Description>

      <Quantity>2</Quantity>

      <Value>2.22</Value>

      <NetPounds></NetPounds>

      <NetOunces>2</NetOunces>

      <HSTariffNumber>234567</HSTariffNumber>

   <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 3</Description>

      <Quantity>3</Quantity>

      <Value>3.33</Value>

      <NetPounds></NetPounds>

      <NetOunces>3</NetOunces>

      <HSTariffNumber>123456</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 4</Description>

      <Quantity>4</Quantity>

      <Value>4.44</Value>

      <NetPounds></NetPounds>

      <NetOunces>4</NetOunces>

      <HSTariffNumber>234567</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 5</Description>

      <Quantity>5</Quantity>

      <Value>5.55</Value>

      <NetPounds></NetPounds>

      <NetOunces>5</NetOunces>

      <HSTariffNumber>123456</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

    <ItemDetail>

      <Description>Description 6</Description>

      <Quantity>6</Quantity>

      <Value>6.66</Value>

      <NetPounds></NetPounds>

      <NetOunces>6</NetOunces>

      <HSTariffNumber>234567</HSTariffNumber>

      <CountryOfOrigin>Australia</CountryOfOrigin>

    </ItemDetail>

</ShippingContents>

<CustomsContentType>Document</CustomsContentType>

<ContentComments>1234567890123456789012345</ContentComments>

<RestrictionType>Phytosanitary Inspection</RestrictionType>

<RestrictionComments>1234567890123456789012345</RestrictionComments>

<AESITN>12345678901234567890123456789012345</AESITN>

<ImportersReference>123456789012345678901234567890</ImportersReference>

<ImportersContact>Importers Contact: This field can be 50 chars long</ImportersContact>

<ExportersReference>12345678901234</ExportersReference>

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

<InvoiceNumber>Invoice89012345</InvoiceNumber>

<LicenseNumber>License Number12</LicenseNumber>

<CertificateNumber>CertificateX</CertificateNumber>

</eVSCertifyRequest>

 

2.2    eVS Label Response

2.2.1     eVS Response Parameters

Tag Name

Occurs

Description

Type

Validation

eVSResponse

required once

 

(group)

 

eVSResponse/ BarcodeNumber

required once

Tracking Number  

string

 

eVSResponse/ LabelImage

optional

Label image, if requested (where <ImageType> tag not "None") 

base64Binary

 

eVSResponse/ ReceiptImage

optional

Separate Receipt image, if requested using <ReceiptOptions> tag 

base64Binary

 

eVSResponse/ ToName

required once

Name of Recipient  

string

 

eVSResponse/ ToFirm

required once

Company Name  

string

 

eVSResponse/ ToAddress1

required once

To Address Line 1  

string

 

eVSResponse/ ToAddress2

required once

To Address Line 2  

string

 

eVSResponse/ ToCity

required once

To City  

string

 

eVSResponse/ ToState

required once

To State  

string

 

eVSResponse/ ToZip5

required once

To ZIP Code  

string

 

eVSResponse/ ToZip4

required once

To ZIP Code+4  

string

 

eVSResponse/ Postnet

required once

 

string

 

eVSResponse/ RDC

required once

 

string

 

eVSResponse/ Postage

required once

Amount of Postage Required, does not include insurance or other extra service fees.

decimal

 

eVSResponse/ ExtraServices

optional

 

(group)

 

eVSResponse/ ExtraServices/ ExtraService

optional, repeating up to unbounded times

Groups extra service information

(group)

 

eVSResponse/ ExtraServices/ ExtraService/ ServiceID

required once

Extra Service ID echoed from request

string

 

eVSResponse/ ExtraServices/ ExtraService/ ServiceName

required once

Extra Service name

string

 

eVSResponse/ ExtraServices/ ExtraService/ Price

required once

Extra Service fee 

decimal

 

eVSResponse/ HoldForPickup

optional

For future use.  

 

 

eVSResponse/ Zone

required once

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

string

 

eVSResponse/ DimensionalWeight

optional

Dimensional Weight of package, if greater than specified in <WeightInOunces>.

string

 

eVSResponse/ CarrierRoute

required once

Carrier Route

string

 

eVSResponse/ PermitHolderName

required once

Permit Holder Name

string

 

eVSResponse/ InductionType

required once

Permit Holder Induction Type

string

 

eVSResponse/ LogMessage

required once

A text message for integrators of this API. It may contain additional information about this particular request/ response, or general information about the API or Web Tools. In typical implementations, whenever this tag is encountered, the message is written to the console log file for later analysis.  

string

 

eVSResponse/

Commitment

optional

Returned when <ReturnCommitments> = “true” in the request.

 

 

eVSResponse/

Commitment/

CommitmentName

required once

Commitment name.

 

Example “1-Day”.

string

 

eVSResponse/

Commitment/

ScheduledDeliveryDate

required once

Date of delivery. Format “YYYY-MM-DD”.

 

Example “2015-06-03”.

string

 

eVSResponse

required once

 

(alias)

 

 

2.2.2     eVS Response Example

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

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

- <eVSCertifyResponse xmlns:xsi="http:/ / www.w3.org/ 2001/ XMLSchema-instance">

 <BarcodeNumber>420063719270110101010XXXXXXXXX</ BarcodeNumber>

  <LabelImage>SUkqAAgAAAASAP4ABAAB

    <!-- over 115000 suppressed -->

  </ LabelImage>

  <ToName>TOM COLLINS</ ToName>

  <ToFirm>XYZ CORP.</ ToFirm>

  <ToAddress1>STE 4D</ ToAddress1>

  <ToAddress2>8 WILDWOOD DR</ ToAddress2>

  <ToCity>OLD LYME</ ToCity>

  <ToState>CT</ ToState>

  <ToZip5>06371</ ToZip5>

  <ToZip4>1844</ ToZip4>

  <Postnet>063711844088</ Postnet>

  <RDC>0007</ RDC>

  <Postage>18.11</ Postage>

  <Zone>00</ Zone>

  <CarrierRoute>R###</ CarrierRoute>

  <PermitHolderName>TEST - DO NOT MAIL</ PermitHolderName>

  <InductionType>ePostage</ InductionType>

  <LogMessage></ LogMessage>

</ eVSCertifyResponse>

 

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

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

- <eVSCertifyResponse xmlns:xsi="http:/ / www.w3.org/ 2001/ XMLSchema-instance">

 <BarcodeNumber>420063719270110101010XXXXXXXXX</ BarcodeNumber>

  <LabelImage>SUkqAAgAAAASAP4ABAAB

    <!-- over 115000 suppressed -->

  </ LabelImage>

  <ToName>TOM COLLINS</ ToName>

  <ToFirm>XYZ CORP.</ ToFirm>

  <ToAddress1>STE 4D</ ToAddress1>

  <ToAddress2>8 WILDWOOD DR</ ToAddress2>

  <ToCity>OLD LYME</ ToCity>

  <ToState>CT</ ToState>

  <ToZip5>06371</ ToZip5>

  <ToZip4>1844</ ToZip4>

Postnet>090943300994</Postnet>

<RDC>0006</RDC>

<Postage>5.05</Postage>

<ExtraServices><ExtraService>

<ServiceID>155</ServiceID>

<ServiceName>USPS Tracking Electronic</ServiceName>

<Price>0.00</Price>

</ExtraService>

</ExtraServices>

<Zone>01</Zone>

<CarrierRoute>C000</CarrierRoute>

<PermitHolderName>TEST – DO NOT MAIL</PermitHolderName>

<InductionType>eVS</InductionType>

<LogMessage/>

<Commitment>

<CommitmentName>Military</CommitmentName>

<ScheduledDeliveryDate/>

</Commitment>

</eVSCertifyResponse>

 

2.2.3     eVS Label Example – Express

Defect_470_CR286_LIVE-3-LabelImage


 

2.2.4     eVS Label Example – Express Customs Form

EVS - express

EVS - express

2.2.5     eVS Label Example – Priority and First Class

Defect_470_CR286_LIVE-2-LabelImage


 

2.2.6     eVS Label Example – Priority Customs Form

EVS

EVS

2.2.7     eVS Label Example – Library Mail


 

2.2.8     eVS Label Example – Media Mail


 

2.2.9     eVS Label Example – BPM


 

2.2.10  eVS Label Example – Priority Mail Cubic


 

2.3    eVS Cancel Request

The eVS Cancel request allows an eVS label to be removed from processing.

Note: If a record is canceld before it manifests, it may still appear on the scan form.

2.3.1   API Signature

Scheme

Host

Path

API

XML

https://

secure.shippingapis.com

/ShippingAPI.dll?

API=eVSCancel

&XML=(see below)

2.3.2     eVS Cancel Request Parameters

Tag Name

Occurs

Description

Type

Validation

eVSCancelRequest

required once

 

(group)

 

eVSCancelRequest/ @USERID

required

 

NMTOKEN

 

eVSCancelRequest/ @PASSWORD

optional

 

NMTOKEN

 

eVSCancelRequest / BarcodeNumber

required

BarcodeNumber of original label.

Length of 22, 30 or 34 numbers.

 

eVSCancelRequest

required

 

 

 

 

2.3.3     eVS Cancel Request Examples

<eVSCancelRequest USERID="xxxx">

  <BarcodeNumber>420902109411202901089817001111</BarcodeNumber>

</eVSCancelRequest>

 

 

eVS Cancel Response

2.3.4     eVS Cancel Response Parameters

Tag Name

Occurs

Description

Type

Validation

eVSCancelResponse

required once

 

(group)

 

eVSCancelResponse/ @USERID

required

 

NMTOKEN

 

eVSCancelResponse/ @PASSWORD

optional

 

NMTOKEN

 

eVSCancelResponse / BarcodeNumber

required

Returned in the eVS Label Request

Length of 22, 30 or 34 numbers.

 

eVSCancelResponse / Status

required

Success or Failure Indicator

string

“Cancelled”

“Not Cancelled”

eVSCancelResponse / Reason

required

 

string

“Order Cancelled Successfully”

“Order Already Cancelled”

“Order Not Found”

eVSCancelResponse

required

 

 

 

 

2.3.5     eVS Cancel Response Examples

<?xml version="1.0"?>

<eVSCancelResponse>

  <BarcodeNumber>420902109411202901089817001111</ BarcodeNumber>

  <Status>Cancelled</ Status>

  <Reason>Order Cancelled Successfully</ Reason>

</ eVSCancelResponse>

 

<?xml version="1.0"?>

<eVSCancelResponse>

  <BarcodeNumber>420902109411202901089817001111</ BarcodeNumber>

  <Status>Not Cancelled</ Status>

  <Reason>Order Already Cancelled</ Reason>

</ eVSCancelResponse>

 

 

<?xml version="1.0"?>

<eVSCancelResponse>

  <BarcodeNumber>420902109411202901089817001111</ BarcodeNumber>

  <Status>Not Cancelled</ Status>

  <Reason>Order Not Found</ Reason>

</ eVSCancelResponse>