This document contains a Reference Guide to the eVS Label API. 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. Web Tools 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:

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

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 mail pieces 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 and http://pe.usps.com/text/dmm300/608.htm.

1.1 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.0 eVS Label API

2.1 Overview

The only option for creating outbound shipping 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

· Requires enrollment and new Mailer IDs (MIDs) and permits

· Supports domestic/international/APO/FPO/DPO/PTFAS locations

· Supports Priority Mail Cubic and Parcel Select Ground Cubic (Contact your Technical Integration Specialist for further details)

· Supports Parcel Select Destination Entry (PSDE) and Parcel Select Lightweight (PSLW) label creation.

· Supports Global Direct Entry (GDE)

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.

If you want to explore using eVS, please first contact the eVS@usps.gov.

For registration please visit: https://www.usps.com/postalone/evs.htm. If that will not work for you, then you can follow up with sales@usps.gov (or your local Postmaster or USPS Sales Manager) for additional solutions outside of the Web Tools API suite.

Note: The “eVSCertify” 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=eVS	&XML=(see below)
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=eVSCertify	&XML=(see below)

2.2 Request Descriptions

Tag Name

Occurs

Description

Type

Validation

eVSRequest

Required

API=eVS

(Group)

eVSRequest/ USERID

Required

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

For Example: <USERID=”XXXXXXXXXXXX”>

NMTOKEN

eVSRequest/

Option

Optional

For future use.

Empty

eVSRequest/ Revision

Optional

Use value of “1” for new abbreviated addresses logic.

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)

· 4X6ZPL203DPI - (ZPL - Zebra Programming Language) format. When using this enumeration, <ImageType> 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, <ImageType> 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.

· 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

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

String

Default=4X6LABEL

Enumerations=

· BARCODE ONLY

· CROP

· 4X6LABEL

· 4X6LABELL

· 6X4LABEL

· 4X6LABELP

· 4X6LABELP PAGE

· 4X6ZPL203DPI

· 4X6ZPL300DPI

· SEPARATECONTINUEPAGE

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 only one package.

String

minOccurs="0" maxOccurs="1"

eVSRequest / ImageParameters/ LabelSequence / PackageNumber

Required

Required if <LabelSequence> is selected

Integer

minInclusive value = "1"

maxInclusive value = "999"

eVSRequest / ImageParameters / LabelSequence/ TotalPackages

Required

Required if <LabelSequence> is selected

Integer

minInclusive value = "1"

maxInclusive value = "999"

eVSRequest/ FromName

Required

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

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

For example: <FromFirm>USPS</FromFirm>

Note: Maximum length printed on the label is 32 characters for all <ServiceType> enumerations. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.

String

minLength=0
maxLength=50

eVSRequest/ FromAddress1

Optional

From address line 1. Use this field for secondary address information such as an apartment or suite number if applicable.

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

Note: When populating the address fields, do not include additional information such as building name or company.

String

minLength=0
maxLength=50

eVSRequest/ FromAddress2

Required

From address line 2. Use this field for a primary street address.

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

Note: When populating the address fields, do not include additional information such as building name or company.

String

minLength=1
maxLength=50

eVSRequest/ FromCity

Required

From city.

For example: <FromCity>BETHESDA</ FromCity>

String

minLength=1
maxLength=28

eVSRequest/ FromState

Required

From state. Value should be passed as two-letter state abbreviation.

For example: <FromState>MD</FromState>

String

minLength=2
maxLength=2

eVSRequest/ FromZip5

Required

From ZIP code.

For example: <FromZip5>20212</FromZip5>

String

pattern=\d{5}

eVSRequest/ FromZip4

Optional

From ZIP+4 extension.

For example: <FromZip4>2402</FromZip4>

String

minLength=0
pattern=\d{4}

eVSRequest/ FromPhone

Optional

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

For example: <FromPhone>2125551234</ FromPhone>

Note: This field is used to return on the receipt and label only when <ServiceType> = “PRIORITY EXPRESS”.

String

pattern=\d{10}

eVSRequest/ POZipCode

Optional

ZIP Code of Post Office or collection box where item is mailed. May be different than FromZip5. This tag will take precedence over FromZip5 when provided.

For example: <POZipCode>20770</ POZipCode>

Note: Required when <ServiceType>= “PARCEL SELECT DE” or “PARCEL SELECT LW”.

String

minLength=0
maxLength=5

eVSRequest/ AllowNonCleansedOriginAddr

Optional

Allows Non-Validated Origin Street Address. Enter “true” to bypass street address validation failures/errors or “false” if only validated addresses should be allowed.

For example:

<AllowNonCleansedOriginAddr>True

</ AllowNonCleansedOriginAddr>

Note: Integrators are recommended to always use “false” to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when “true” is indicated to allow label creation which could impact delivery. The <AllowNonCleansedOriginAddr> excludes City, State, and ZIP Code which must be valid for a successful response. Reference https://pe.usps.com/text/pub28/28c2_001.htm.

Boolean

Default=False

Enumerations=

· True

· False

eVSRequest/ ToName

Required

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

For example: <ToName>Smith</ ToName>

String

minLength=0
maxLength=100

eVSRequest/ ToFirm

Required

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

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

Note: Maximum length printed on the label is 28 characters for all <ServiceType> enumerations. Values exceeding 28 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.

String

minLength=0
maxLength=50

eVSRequest/ ToAddress1

Optional

Recipient address line 1. Use this field for secondary address information such as an apartment or suite number if applicable.

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

Note: When populating the address fields, do not include additional information such as building name or company.

String

minLength=0
maxLength=50

eVSRequest/ ToAddress2

Required

Recipient address line 2. Use this field for a primary street address.

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

Note: When populating the address fields, do not include additional information such as building name or company.

String

minLength=1
maxLength=50

eVSRequest/ ToCity

Required

Recipient city.

For example: <ToCity>ANYTOWN</ ToCity>

String

minLength=0
maxLength=28

eVSRequest/ ToState

Required

Recipient state.

For example: <ToState>MN</ ToState>

String

minLength=0
pattern=\w{2}

eVSRequest/ ToZip5

Required

Recipient ZIP code.

For example: <ToZip5>12345</ ToZip5>

String

minLength=0
pattern=\d{5}

eVSRequest/ ToZip4

Optional

Recipient ZIP+4 extension.

For example: <ToZip4>1844</ToZip4>

String

minLength=0
pattern=\d{4}

eVSRequest/ ToPhone

Optional

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

For example: <ToPhone>2125551234</ ToPhone>

Note: This field is used to return on the receipt only when <ServiceType> = “PRIORITY EXPRESS”.

String

pattern=\d{10}

eVSRequest/ POBox

Optional

Indicates if destination address is a PO Box.

For example: <POBox>True</ POBox>

Boolean

Default=False

Enumerations=

· True

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

Note: For future use

String

whiteSpace=collapse

Enumerations=

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

Note: For future use

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.

For example:

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

Note: For future use

String

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

eVSRequest/ AllowNonCleansedDestAddr

Optional

Allows Non-Validated Destination Street Address. Enter “true” to bypass street address validation failures/errors or “false” if only validated addresses should be allowed.

For example: <AllowNonCleansedDestAddr>true</AllowNonCleansedDestAddr>

Note: Integrators are recommended to always use “false” to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when “true” is indicated to allow label creation which could impact delivery. The <AllowNonCleansedDestAddr> excludes City, State, and ZIP Code which must be valid for a successful response. Reference https://pe.usps.com/text/pub28/28c2_001.htm.

Boolean

Default=False

Enumerations=

· True

· False

eVSRequest/ WeightInOunces

Required

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

For example: <WeightInOunces>80</ WeightInOunces>

String

pattern=\d{0,4}

eVSRequest/ ServiceType

Required

Mail service type desired. For example: <ServiceType>PRIORITY</ ServiceType>

Note: For Priority Mail Cubic, the following is required:

· Additional permissions. See section 2.1 Overview

· <ServiceType> must equal “PRIORITY MAIL CUBIC”

· <Container> must equal “CUBIC PARCELS” or “CUBIC SOFT PACK”

· <PriceOptions> can equal “Commercial Plus” or “Commerical Base”

It is recommended to pass the largest Cubic dimension as “Length” in <Length> request tag and the second largest dimension as “Width” in <Width> request tag.

Note: To utilize <ServiceType>= “PARCEL SELECT GROUND CUBIC” access must be granted per Web Tools USERID otherwise an error will return.

Note: When <Service>= “Parcel Select Ground Cubic” only “CUBIC PARCELS” or “CUBIC SOFT PACK” are valid <Container> options. It is recommended to pass the largest Cubic dimension as “Length” in <Length> request tag and the second largest dimension as “Width” in <Width> request tag.

Note: Web Tools will verify when <ServiceType> = “PARCEL SELECT DE” or “PARCEL SELECT LW” the new Parcel Select Destination Entry permissions are also granted otherwise an error will be returned.

Note: When <ServiceType> options “PARCEL SELECT DE” or “PARCEL SELECT LW”, the <POZipCode> request tag will be required to collect Destination Entry Facility ZIP Code and populate SSFv2.0 H1 pos 7 (Entry Facility ZIP Code) field.

Note: Web Tools will return an error if <OptOutOfSPE>= “false” when <ServiceType> = “PARCEL SELECT DE” or “PARCEL SELECT LW”.

String

Enumerations=

· PRIORITY EXPRESS

· PRIORITY

· PRIORITY MAIL CUBIC

· FIRST CLASS

· PARCEL SELECT GROUND

· PARCEL SELECT GROUND CUBIC

· LIBRARY

· MEDIA

· BPM

· PARCEL SELECT LW

· PARCEL SELECT DE

eVSRequest/ Container

Optional

Use to specify USPS containers/packaging or container attributes that may affect postage. If null value is supplied, then default container will be “VARIABLE”. For example: <Container>FLAT RATE ENVELOPE</Container>

String

whiteSpace=collapse

Default=VARIABLE

Enumerations=

· 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

· PACKAGE SERVICE

· CUBIC PARCELS

· CUBIC SOFT PACK

eVSRequest/ Width

Optional

Value must be numeric. Units are inches. If 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 DMM https://pe.usps.com/text/dmm300/index.htm

Decimal

minExclusive=0.0
totalDigits=10

eVSRequest/ Length

Optional

For more details on dimensional weight pricing or dimension validation reference DMM https://pe.usps.com/text/dmm300/index.htm

Decimal

minExclusive=0.0
totalDigits=10

eVSRequest/ Height

Optional

For more details on dimensional weight pricing or dimension validation reference DMM https://pe.usps.com/text/dmm300/index.htm

Decimal

minExclusive=0.0
totalDigits=10

eVSRequest / Girth

Optional

Value must be numeric. Units are inches. If 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 DMM https://pe.usps.com/text/dmm300/index.htm

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>

Note: The default value is dependent on the <ServiceType> requested.

Note: The First Class service type in conjunction with a <PriceOption> of ‘Commercial Plus’ will result in a ‘True’ default Machinable value. For all other scenarios, the <PriceOption> field will not impact the default Machinable value.

<ServiceType>	Default Value
FIRST CLASS	False
FIRST CLASS and when <PriceOptions> = “Commercial Plus”	True
PRIORITY	True
PRIORITY EXPRESS	True
PRIORITY MAIL CUBIC	True
MEDIA	True
LIBRARY	True
BPM	True
PARCEL SELECT GROUND	Value is True if <WeightinOunces> is over 560 or a calculated value is over 108. Otherwise, value is False.

String

Enumerations=

· True

· False

· Irregular

eVSRequest/ PriceOptions

Optional

Indicates pricing that should be returned. For example:

<PriceOptions>Commercial Base</ PriceOptions>

Required when <ServiceType>= “PRIORITY MAIL CUBIC” <PriceOptions> must equal “Commercial Plus”.

String

Default=Commercial Base

Enumerations=

· Commercial Plus

· Commercial Base

eVSRequest/ InsuredAmount

Optional

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

For example:

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 mail piece 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 mail piece is returned with the new address attached at no charge. After 18 months, or if undeliverable, the mail piece is returned with the reason for nondelivery attached at no charge. For fees for this service with Package Services, refer to the Domestic Mail Manual.

For example: <AddressServiceRequested>True</AddressServiceRequested>

Boolean

Default=False

Enumerations=

· True

· False

eVSRequest/ ExpressMailOptions

Optional

Groups Express Mail Delivery and Signature options. Valid when <ServiceType>=“PRIORITY 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

Enumerations=

· 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

Enumerations=

· True

· False

eVSRequest/ ExpressMailOptions/eSOFAllowed

Optional

Electronic Signature On File Allowed. This value is used to allow retailers to request that Electronic Signature On File (eSOF) be overridden such that a physical or “wet” signature is required. This field should be populated with “False” to request that the use of eSOF be disallowed for the shipment.

For example: <eSOFAllowed>False</eSOFAllowed>

Boolean

Default=True

Enumerations=

· True

· False

eVSRequest/ ShipDate

Optional

Date Package Will Be Mailed. Ship date may be today plus 0 to 7 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:

Note: The <PrintCustomerRefNo> must be set to “true” to be printed on the label.

Located in position #21 in the Detail 1 record of the Shipping Services File v2.0.

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.

Required when <ePostageMailerReporting>=”1” For example:

Note: The <PrintCustomerRefNo2> must be set to “true” to be printed on the label.

Located in position #76 in the Detail 1 record of the Shipping Services File v2.0.

Required when <ePostageMailerReporting>= “1”

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.

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
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
Scan Retention	181
Scan + Signature Retention	182

Note: When <ExtraService>=“125” is indicated and insured amount is less than or equal to $100, the insurance price returned will be zero (“$0.00”) to reflect baked-in insurance. If insured amount is greater than $100, the insurance price returned will reflect an extra cost since baked-in insurance was exceeded.

String

whiteSpace=collapse

Enumerations=

· 100

· 101

· 102

· 105

· 110

· 118

· 119

· 120

· 125

· 155

· 156

· 170

· 171

· 172

· 174

· 177

· 178

· 179

· 181

· 182

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.

Located in position #20 in the Detail 1 record of the Shipping Services File v2.0.

For example: <CRID>544762</CRID>

String

minLength=0
maxLength=15

eVSRequest/ MID

Optional

Mailer ID (MID), Represents Mail Owner MID.

Located in position #13 in the Detail 1 record of the Shipping Services File v2.0.

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. For example: <LogisticsManagerMID>489001</ LogisticsManagerMID>

Note: If <LogisticsManagerMID> is populated, either CRID or MID must also be populated. Located in position #12 in the Detail 1 record of the Shipping Services File v2.0.

String

Length=6 or 9 positions if populated

eVSRequest/ VendorCode

Optional

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

Located in position #15 in the Detail 1 record of the Shipping Services File v2.0.

For example: <VendorCode>1234<VendorCode>

String

minLength=0
maxLength=4

default=8300

eVSRequest/ VendorProductVersionNumber

Optional

Shipping software’s product version number.

Located in position #16 in the Detail 1 record of the Shipping Services File v2.0.

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

String

minLength=0
maxLength=8

eVSRequest/ SenderName

Optional

The name of the person or company sending the USPS tracking email notification.

Note: No email is returned when generating a Sample (i.e. API=eVSCertify) request.

String

minLength=0

maxLength=50

eVSRequest/ SenderEMail

Optional

Email address of sender used for USPS tracking email notification. Valid email addresses must be used.

Note: <RecipientEMail> must be populated to generate USPS tracking email notification. If <SenderEMail> provided without <RecipientEMail>, USPS tracking email notification will not be generated.

Note: No email is returned when generating a Sample (i.e. API=eVSCertify) request.

String

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

eVSRequest/ RecipientName

Optional

The name of the person or company receiving the USPS tracking email notification. If recipient name not provided, email will be addressed to <RecipientEMail> value provided.

String

minLength=0

maxLength=50

eVSRequest/ RecipientEMail

Optional

Email address of recipient receiving the USPS tracking email notification. This field is required to generate tracking email. Valid email addresses must be used.

Note: No email is returned when generating a Sample (i.e. API=eVSCertify) request.

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:

Note: When <ImageParameter> = “4X6ZPL203DPI” or “4X6ZPL300DPI” a receipt is eligible to return but it will not be ZPL encoded.

String

Default=SAME PAGE

Enumerations=

· SEPARATE PAGE

· SAME PAGE

· NONE

eVSRequest/ ImageType

Required

Label Image Type. For example: <ImageType>PDF</ ImageType>

Note: All <ImageType> values are ignored when <ImageParameter>= “4X6ZPL203DPI” or “4X6ZPL300DPI”.

String

Enumerations=

· PDF

· TIF

· NONE

eVSRequest/ HoldForManifest

Optional

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

String

Default=N

Enumerations=

· Y

· N

eVSRequest/ NineDigitRoutingZip

Optional

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

For example:

<NineDigitRoutingZip>False</ NineDigitRoutingZip>

Note: This request tag must equal “true” for a 9-digit ZIP to be included in the barcode otherwise, even if <ToZip4> is provided in the request it will not be present in the barcode.

Boolean

Default=False

Enumerations=

· True

· False

eVSRequest/ ShipInfo

Optional

Indicates if revenue protection information is printed on the label.

For example:

<ShipInfo>False</ShipInfo>

Boolean

Default=False

Enumerations=

· True

· 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

Enumerations=

· True

· False

eVSRequest/

DropOffTime

Optional

Indicates the time the package will be dropped off.

Time is specified in military time.

For example:

Boolean

eVSRequest/

ReturnCommitments

Optional

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

For example:

<ReturnCommitments>False</ ReturnCommitments>

Boolean

Default=False

Enumerations=

· True

· False

eVSRequest/

PrintCustomerRefNo

Optional

Print <CustomerRefNo> in the additional information section.

Note: For the <CustomerRefNo> value to print on the label you must also indicate “True” for the <PrintCustomerRefNo> tag.

Boolean

Default=False

Enumerations=

· True

· False

eVSRequest/

PrintCustomerRefNo2

Optional

Print <CustomerRefNo2> in the additional information section.

Note: For the <CustomerRefNo2> value to print on the label you must also indicate “True” for the <PrintCustomerRefNo2> tag.

Boolean

Default=False

Enumerations=

· True

· False

eVSRequest/

Content

Optional

Groups Content

(Group)

eVSRequest/

Content/ ContentType

Conditionally Required

(Required when Content grouping is included)

Use to specify ContentType. Currently available types are:

ContentType

HAZMAT

CrematedRemains

Lives

Perishable

Pharmaceuticals

MedicalSupplies

For example: <ContentType>Lives</ContentType >

String

Enumerations=

· HAZMAT

· CrematedRemains

· Lives

· Perishable

· Pharmaceuticals

· MedicalSupplies

eVSRequest/

Content/ ContentDescription

Conditionally Required

(Required when Content grouping is included)

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

Enumerations=

· Bees

· DayOldPoultry

· AdultBirds

· Other

eVSRequest/ActionCode

Optional

Used to specify the action code. Value is included in the Shipping Partner Event file for customers who have chosen to have a Shipping Partner Event file submitted to USPS on their behalf.

M0 – Mailer Owner

S0 – Service Provider

For example: <ActionCode>M0</ActionCode>

String

Default =M0

Enumerations=

· M0

· S0

eVSRequest/ OptOutOfSPE

Optional

Used to specify if a SPE file will be created.

For example: <OptOutOfSPE> false </OptOutOfSPE>

Note: Web Tools will return an error if <OptOutOfSPE>= “false” when <ServiceType> = “PARCEL SELECT DE” or “PARCEL SELECT LW”.

Note: This request tag is case sensitive.

Boolean

Default=true

Enumerations=

· true

· false

eVSRequest/

SortationLevel

Conditionally Required

Note: Required when <ServiceType>= “PARCEL SELECT DE” or “PARCEL SELECT LW”.

Sortation Level	Value
3-Digit	3D
Origin Entry	None
3-Digit implied	Mix
3-Digit implied	SCF
5-Digit	5D

String

Enumerations=

· 3D

· None

· NDC

· Mix

· SCF

· 5D

eVSRequest/

DestinationEntryFacilityType

Conditionally Required

Note: Required when <ServiceType>= “PARCEL SELECT DE” or “PARCEL SELECT LW”.

Destination Type	Value
Destination Delivery Unit	DDU
Destination Network Distribution Unit	DNDC
Destination Sectional Center Facility	DSCF

String

Enumerations=

· DDU

· DNDC

· DSCF

· NONE

eVSRequest/

ContainerID1

Conditionally Required

Barcode on container 1.

For example: <ContainerID1>222010127123456789912345</ContainerID1>

Note: Required when <DestinationEntryFacilityType> = “DNDC” or “DSCF”

String

maxLength=34,

minLength=0

Alphanumeric (34)

eVSRequest/

ContainerID2

Optional

Barcode on container 2.

For example: <ContainerID2>222010127123456789912345</ContainerID2>

String

maxLength=34,

minLength=0

Alphanumeric (34)

eVSRequest/

ContainerID3

Optional

Barcode on container 3.

For example: <ContainerID3>222010127123456789912345</ContainerID3>

String

maxLength=34,

minLength=0

Alphanumeric (34)

eVSRequest/

SortContainerType1

Conditionally Required

Describes type of container for ContainerID1.

Note: Required if <ContainerID1> is populated

Sort Container	Value
Pallet	PT
Sack	SACK

String

maxLength=2,

minLength=0

Enumerations=

· PT

· SK

eVSRequest/

SortContainerType2

Conditionally Required

Describes type of container for ContainerID2.

Note: Required if <ContainerID2> is populated

String

maxLength=2,

minLength=0

Enumerations=

· PT

· SK

eVSRequest/

SortContainerType3

Conditionally Required

Describes type of container for ContainerID3.

Note: Required if <ContainerID3> is populated

String

maxLength=2,

minLength=0

Enumerations=

· PT

· SK

eVSRequest/

DiscountType

Optional

This tag is used to pass applicable discount codes. Refer to Pub199, Appendix J, Table 6 for the complete list of Discount Type codes.

https://postalpro.usps.com/pub199

For Example:

String

maxLength=2,

minLength=0

2-digit alphanumeric

eVSRequest/

DiscountAmount

Optional

This tag is used to pass the discount fee.

For Example:

Decimal

maxLength=8,

minLength=0

eVSRequest/

SurchargeType

Conditionally Required

This tag is used to pass applicable surcharge codes. Refer to Pub199, Appendix J, Table 13 for the complete list of Surcharge Type codes.

https://postalpro.usps.com/pub199

For Example:

Note: Required when <NextDay> = “Y”.

String

maxLength=2,

minLength=0

2-digit alphanumeric

eVSRequest/

SurchargeAmount

Conditionally Required

This tag is used to pass the surcharge fee.

For Example:

Note: Required when <NextDay> = “Y”.

Decimal

maxLength=7,

minLength=0

eVSRequest/

ShipmentFeeCode

Optional

This tag is used to pass a Pickup on Demand fee code.

For Example:

String

maxLength=3,

minLength=0

Alphanumeric (3)

eVSRequest/

ExtraFeeForShipment

Optional

This tag is used to pass a Pickup on Demand fee.

For Example:

Decimal

maxLength=7,

minLength=0

pattern= ^\d{1,4}([.]\d{1,2})?$

eVSRequest/

NextDay

Optional

Same Day/Next Day Program Indicator

Note: When “Y”, <SurchargeType> of “E2” (Same Day/Next Day) and <SurchargeAmount> required otherwise an error will be returned.

Note: When “Y”, "SAME DAY DELIVERY" endorsement and carrier release “CARRIER – LEAVE IF NO RESPONSE" markings will be displayed on the label.

Note: <NextDay> indicator will take precedence over <CarrierRelease> tag when determining markings printed on the label.

Boolean

Default=no

Enumerations=

· Y

· N

eVSRequest / ShippingContents

Conditionally Required

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

(Group)

eVSRequest / ShippingContents / ItemDetail

Required repeating up to 30 times or optional

Required 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

Enumerations=

· 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

Enumerations=

· 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

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

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

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

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

Invoice Number

String

minOccurs=0

maxOccurs=15

eVSRequest / LicenseNumber

Optional

License Number

String

minOccurs=0

maxOccurs=16

eVSRequest / CertificateNumber

Optional

Certificate Number

String

minOccurs=0

maxOccurs=12

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

Enumerations=

· RETURN

· REDIRECT

· ABANDON

eVSRequest / AltReturnAddress1

Optional

Required <NonDeliveryOption>=”REDIRECT”.

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

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

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

String

minOccurs=0

eVSRequest / AltReturnAddress2

Optional

Required <NonDeliveryOption>=”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: Six AltReturn Address lines are provided but only one line is required. Use as many as needed for complete address.

String

minOccurs=0

eVSRequest / AltReturnAddress3

Optional

Required <NonDeliveryOption>=”REDIRECT”.

Suggested use of this tag is the Recipient city.

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

String

minOccurs=0

eVSRequest / AltReturnAddress4

Optional

Required <NonDeliveryOption>=”REDIRECT”.

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

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

String

minOccurs=0

eVSRequest / AltReturnAddress5

Optional

Required <NonDeliveryOption>=”REDIRECT”.

Suggested use of this tag is the recipient ZIP code.

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

String

minOccurs=0

eVSRequest / AltReturnAddress6

Optional

Required <NonDeliveryOption>=”REDIRECT”.

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

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

String

minOccurs=0

eVSRequest / AltReturnCountry

Optional

Required <NonDeliveryOption>=”REDIRECT”.

Country. Tag must equal United States for this API.

String

minOccurs=0

eVSRequest/

LabelImportType

Optional

This tag is used by USPS meter label solution (MLS) for tracking purposes.

For example: <LabelImportType>CSV</LabelImportType>

String

eVSRequest/

ePostageMailerReporting

Optional

Used to identify ePostage sender/mailer and include Sender information in SSF.

· 1 (ePostage sender info in SSF)

· 2 (ePostage sender info through DES)

· 3 (ePostage sender info using child MID)

Verifies Sender informationsender fields are provided and must match From information when <ePostageMailerReporting>=1

ePostageMailerReporting value used in SSF for “PostageType”

String

Enumerations=

· 1

· 2

· 3

eVSRequest/

SenderFirstName

Optional

First Name of Sender.

For example:

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. Use this tag for complete sender address

For example: <SenderAddress1>123 Main 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 / ChargebackCode

Optional

Used in Shipping Services File v2.0 for G-10 labels. Contact your Technical Integration Specialist for details.

String

123456 (alphanumeric)

eVSRequest / TrackingRetentionPeriod

Optional

Used to determine period of Retention for tracking data. Required when <ExtraService>= “181” or “182”.

ServiceID	<TrackingRetentionPeriod>
181	“0.5” (6 Months)
181	“1” (1 Year)
181	“3” (3 Years)
181	“5” (5 Years)
181	“7” (7 Years)
182	“3” (3 Years)
182	“5” (5 Years)
182	“7” (7 Years)

String

minOccurs=0

maxOccurs=1

Enumerations=

· 0.5

· 1

· 3

· 5

· 7

eVSRequest/ReturnFees

Optional

This tag must be set to “true” for <Fees> to be returned. This tag is used so customers can see what fees apply to their postage.

Boolean

Default=false

Enumerations=

• true

• false

eVSRequest Request

Required

(alias)

2.2.1 Sample Request

Request: eVS - Domestic

</LabelSequence>

</ImageParameters>

<FromName>Lina Smith</FromName>

<FromFirm>Horizon</FromFirm>

<FromAddress2>1309 S Agnew Avenue</FromAddress2>

<FromCity>Oklahoma City</FromCity>

<AllowNonCleansedOriginAddr>false</AllowNonCleansedOriginAddr>

<ToAddress2>1098 N Fraser Street</ToAddress2>

<ToCity>Georgetown</ToCity>

<ToContactPreference>email</ToContactPreference>

<ToContactEMail>talltom@aol.com</ToContactEMail>

<AllowNonCleansedDestAddr>false</AllowNonCleansedDestAddr>

<ServiceType>PRIORITY</ServiceType>

<Container>VARIABLE</Container>

</ExpressMailOptions>

</ExtraServices>

<SenderName>Adam Johnson</SenderName>

<RecipientName>Robert Jones</RecipientName>

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

<NineDigitRoutingZip>false</NineDigitRoutingZip>

<CarrierRelease>False</CarrierRelease>

<PrintCustomerRefNo>False</PrintCustomerRefNo>

<ContentType>Perishable</ContentType>

<ContentDescription>Other</ContentDescription>

</Content>

<OptOutOfSPE>false</OptOutOfSPE>

</eVSRequest>

Request: eVS – returns integrated Customs Form required for APO/FPO/DPO+PTFAS destinations:

</LabelSequence>

</ImageParameters>

<FromName>Joe Smith</FromName>

<FromAddress2>1309 S Agnew Avenue</FromAddress2>

<FromCity>Oklahoma City</FromCity>

<AllowNonCleansedOriginAddr>false</AllowNonCleansedOriginAddr>

<ToName>Tom Collins</ToName>

<ToAddress1>Suite 4D</ToAddress1>

<ToAddress2>8 Wildwood Drive</ToAddress2>

<POBox>False</POBox>

<ServiceType>PRIORITY</ServiceType>

<Container>VARIABLE</Container>

</ExpressMailOptions>

</ExtraServices>

<SenderName>Joe Smith</SenderName>

<SenderEMail>myemail@email.com</SenderEMail>

<RecipientEMail>youremail@email.com</RecipientEMail>

<NineDigitRoutingZip>False</NineDigitRoutingZip>

<ShipInfo>False</ShipInfo>

<CarrierRelease>False</CarrierRelease>

<ContentType>HAZMAT</ContentType>

<ContentDescription>OTHER</ContentDescription>

</Content>

<Description>Cleaning Wipes</Description>

<CountryOfOrigin>UNITED STATES</CountryOfOrigin>

</ItemDetail>

</ShippingContents>

<CustomsContentType>MERCHANDISE</CustomsContentType>

<ContentComments>Wipes</ContentComments>

<RestrictionType>Sanitary Inspection</RestrictionType>

<RestrictionComments>Sanitary Wipes</RestrictionComments>

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

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

<InvoiceNumber>Invoice89012345</InvoiceNumber>

<LicenseNumber>License Number12</LicenseNumber>

<CertificateNumber>CertificateX</CertificateNumber>

</eVSRequest>

Request: eVS – Parcel Select DE

<FromName>Joe Smith</FromName>

<FromAddress1>Suite 101</FromAddress1>

<FromAddress2>901 D Street SW</FromAddress2>

<FromCity>Washington</FromCity>

<AllowNonCleansedOriginAddr>FALSE</AllowNonCleansedOriginAddr>

<ToName>Tom Collins</ToName>

<ToAddress2>200 Short Blvd</ToAddress2>

<ToCity>Dallas</ToCity>

<AllowNonCleansedDestAddr>FALSE</AllowNonCleansedDestAddr>

<ServiceType>Parcel Select DE</ServiceType>

<Container>VARIABLE</Container>

<AddressServiceRequested>false</AddressServiceRequested>

<CustomerRefNo>ABCDEFGH</CustomerRefNo>

<CustomerRefNo2>ABCDEFGH</CustomerRefNo2>

</ExtraServices>

<SenderName>Jose Abcdef</SenderName>

<SenderEMail>abcd@gmail.com</SenderEMail>

<RecipientName>Robert Meier</RecipientName>

<RecipientEMail>abcd@ymail.com</RecipientEMail>

<CarrierRelease>false</CarrierRelease>

</eVSRequest>

Request: eVS – Parcel Select LW

<FromName>Joe Smith</FromName>

<FromAddress1>Suite 101</FromAddress1>

<FromAddress2>901 D Street SW</FromAddress2>

<FromCity>Washington</FromCity>

<AllowNonCleansedOriginAddr>FALSE</AllowNonCleansedOriginAddr>

<ToName>Tom Collins</ToName>

<ToAddress2>200 Short Blvd</ToAddress2>

<ToCity>Dallas</ToCity>

<AllowNonCleansedDestAddr>FALSE</AllowNonCleansedDestAddr>

<ServiceType>Parcel Select LW</ServiceType>

<Container>VARIABLE</Container>

<AddressServiceRequested>false</AddressServiceRequested>

<CustomerRefNo>ABCDEFGH</CustomerRefNo>

<CustomerRefNo2>ABCDEFGH</CustomerRefNo2>

</ExtraServices>

<SenderName>Jose Abcdef</SenderName>

<SenderEMail>abcd@gmail.com</SenderEMail>

<RecipientName>Robert Meier</RecipientName>

<RecipientEMail>abcd@ymail.com</RecipientEMail>

<CarrierRelease>false</CarrierRelease>

</eVSRequest>

Request: eVS – With Non Standard Fees

<ImageParameter>4X6LABELL</ImageParameter>

</ImageParameters>

<FromName>Joe Smith</FromName>

<FromAddress2>430 blackman st.</FromAddress2>

<FromCity>wilkes barre</FromCity>

<ToName>Tom Collins</ToName>

<ToAddress1>Suite 4D</ToAddress1>

<ToAddress2>393 West Portal Avenue</ToAddress2>

<ToCity>San Francisco</ToCity>

<ServiceType>Parcel Select DE</ServiceType>

<Container>VARIABLE</Container>

</ExtraServices>

<RecipientName>Robert Meier</RecipientName>

<ReceiptOption>SEPARATE PAGE</ReceiptOption>

</Content>

</eVSRequest>

2.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
eVSResponse	Required		(group)
eVSResponse / BarcodeNumber	Required	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	Name of Recipient	String
eVSResponse / ToFirm	Required	Company Name	String
eVSResponse / ToAddress1	Required	To Address Line 1	String
eVSResponse / ToAddress2	Required	To Address Line 2	String
eVSResponse / ToAddress2Abbreviation	Optional	USPS abbreviated address line 2 available when <Revision> = “1”	String
eVSResponse / ToCity	Required	To City	String
eVSResponse / ToCityAbbreviation	Optional	USPS abbreviated city available when <Revision> = “1”	String
eVSResponse / ToState	Required	To State	String
eVSResponse / ToZip5	Required	To ZIP Code	String
eVSResponse / ToZip4	Required	To ZIP Code+4	String
eVSResponse / Postnet	Required		String
eVSResponse / RDC	Required		String
eVSResponse / Postage	Required	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	Extra Service ID echoed from request	String
eVSResponse / ExtraServices / ExtraService / ServiceName	Required	Extra Service name	String
eVSResponse / ExtraServices / ExtraService / Price	Required	Extra Service fee	Decimal
eVSResponse / HoldForPickup	Optional	For future use.
eVSResponse / Zone	Required	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	Carrier Route	String
eVSResponse / PermitHolderName	Required	Permit Holder Name	String
eVSResponse/ InductionType	Required	Permit Holder Induction Type	String
eVSResponse / LogMessage	Required	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	Commitment name. Example “1-Day”.	String
eVSResponse / Commitment / ScheduledDeliveryDate	Required	Date of delivery. Format “YYYY-MM-DD”. Example “2015-06-03”.	String
eVSResponse / Fees	Optional	Returned when “Fees” is True Dimensional weight pricing will include length and volume fees to account for cost of processing oversized parcels
eVSResponse / Fee	Required		String
eVSResponse / Fee / FeeType	Required	Indicates what type of Fee is being requested: - Non Standard Length Fee - Non Standard Volume Fee	String
eVSResponse / Fee / FeeType / FeePrice	Required	Non Standard Length Fee(s) a. 15" < x < 22" = $0 (for all packages) b. 22" < x < 30" = $2 (for DDU entered packages) c. 22" < x < 30" = $3 (for DNDC/DSCF entered packages) d. 22" < x < 30" = $4 (for all other packages) e. x > 30" = $7.50 (for DDU entered packages) f. x > 30" = $11.25 (for DNDC/DSCF entered packages) g. x > 30" = $15 (for all other packages) - Non Standard Volume Fee(s) a. x > 2 cubic feet (3546 cubic inches) = $15 (for all packages) Live Animal Transportation Fee(s) a. $0.20 for all packages	String
eVSResponse / Fees / Fee / FeeType / FeePrice / FeeInformation	Required	Fee Information indicates the fee is <Rate>	String
eVSResponse / Fees / Fee / FeeType / FeePrice / FeeInformation / FeeInfo FeeInfoType=”PriceType”	Required	Fee Information indicates the fee is <Rate>	String
eVSResponse / Attributes	Required	When <ReturnFees> = True, the new Attributes tag will return to show Oversize fees and/or Dimensional Weight fees. Any future package attributes that impact a price returned will be included in the attributes tag.	String
eVSResponse / Attributes / AttributeKey	Required	Attribute Key: · DimensionalWeightR = RetailRate · DimensionalWeightCB = Commercial Rate · DimensionalWeightCP = Commerical Plus Rate · Oversized	String
eVSResponse	Required		(alias)

2.3.1 Sample Response

Response - Domestic

<BarcodeNumber>4202944092682XXXXXXXXXXXXXXXXX</BarcodeNumber>

<LabelImage>SUkqAAgAAAASAP4ABAAB</LabelImage>

<ToAddress2>1098 N FRASER ST</ToAddress2>

<ToCity>GEORGETOWN</ToCity>

<ServiceName>Adult Signature Restricted Delivery</ServiceName>

</ExtraService>

</ExtraServices>

<PermitHolderName>Not Valid Test Label</PermitHolderName>

</Commitment>

</eVSResponse>

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

<BarcodeNumber>4200637192061XXXXXXXXXXXXXXXXX</BarcodeNumber>

<LabelImage>SUkqAAgAAAASAP4ABAAB</LabelImage>

<ToName>TOM COLLINS</ToName>

<ToAddress2>8 WILDWOOD DR</ToAddress2>

<ServiceName>Insurance</ServiceName>

</ExtraService>

<ServiceName>USPS Tracking Electronic</ServiceName>

</ExtraService>

</ExtraServices>

<PermitHolderName>Not Valid Test Label</PermitHolderName>

</Commitment>

</eVSResponse>

Response: eVS – Non Standard Fee Example

<BarcodeNumber>4209412792612XXXXXXXXXXXXXXXXX</BarcodeNumber>

<LabelImage>SUkqAAgAAAASAP4ABAAB</LabelImage>

<ToName>TOM COLLINS</ToName>

<ToAddress2>393 WEST PORTAL AVE</ToAddress2>

<ToCity>SAN FRANCISCO</ToCity>

<ServiceName>USPS Tracking Electronic</ServiceName>

</ExtraService>

</ExtraServices>

<PermitHolderName>Not Valid Test Label</PermitHolderName>

</Commitment>

<Fees>

<Fee>

<FeeType>Nonstandard Volume fee > 2 cu. ft.</FeeType>

</FeeInformation>

</Fee>

</Fees>

</Attributes>

</eVSResponse>

3.0 eVS Cancel API

3.1 Overview

The eVS Cancel request allows an eVS label to be removed from processing. This functionality is available only if the eVS label has been held for manifest (i.e. <HoldForManifest>=”Y” is included in eVS 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.

3.1.1 API Signature

Scheme	Host	Path	API	XML
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=eVSCancel	&XML=(see below)

3.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
eVSCancelRequest	Required		(Alias)
eVSCancelRequest/ USERID	Required		NMTOKEN
eVSCancelRequest / BarcodeNumber	Required	Barcode Number of original label.	Length of 22, 30 or 34 numbers.
eVSCancelRequest	Required		(Alias)

3.2.1 Sample Request

<BarcodeNumber>4202944092682XXXXXXXXXXXXXXXXX</BarcodeNumber>

</eVSCancelRequest>

3.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
eVSCancelResponse	Required		(Alias)
eVSCancelResponse/ USERID	Required		NMTOKEN
eVSCancelResponse / BarcodeNumber	Required	Returned in the eVS Label Request	Length of 22, 30 or 34 numbers.
eVSCancelResponse / Status	Required	Success or Failure Indicator Cancelled Not Cancelled	String
eVSCancelResponse / Reason	Required	Order Cancelled Successfully Order Already Cancelled Order Not Found	String
eVSCancelResponse	Required		(Alias)

3.3.1 Sample Response

Response: Order Cancelled Successfully

<BarcodeNumber>4202944092682XXXXXXXXXXXXXXXXX</BarcodeNumber>

<Status>Cancelled</Status>

<Reason>Order Cancelled Successfully</Reason>

</eVSCancelResponse>

Response: Order Already Cancelled

<BarcodeNumber>4202944092682XXXXXXXXXXXXXXXXX</BarcodeNumber>

<Status>Not Cancelled</Status>

<Reason>Order Already Cancelled</Reason>

</eVSCancelResponse>

Response: Order Not Found

<BarcodeNumber>4202944092682XXXXXXXXXXXXXXXXX</BarcodeNumber>

<Status>Not Cancelled</Status>

<Reason>Order Not Found</Reason>

</eVSCancelResponse>

4.0 Appendix A

4.1 Priority Mail Express Label

Letter

Description automatically generated

4.2 Priority Mail Label

Diagram

Description automatically generated

4.3 First Class Label

Diagram, letter

Description automatically generated

4.4 Parcel Select Ground Label

Diagram, letter

Description automatically generated

4.5 Library Mail Label

Diagram, letter

Description automatically generated

4.6 Media Mail Label

Diagram, letter

Description automatically generated

4.7 BPM Label

Diagram

Description automatically generated

4.8 Priority Mail Cubic Label

Letter

Description automatically generated

4.9 Priority Mail Customs Form

Diagram, schematic

Description automatically generated

4.10 Parcel Select Destination Entry

Diagram

Description automatically generated

Figure 1: eVS Parcel Select Destination Entry

4.11 Parcel Select Lightweight

Diagram, letter

Description automatically generated

Figure 2: eVS Parcel Select Lightweight

5.0 Appendix B - Special Situations

5.1 GDE Service

Web Tools allows the eVS Domestic Label API to identify Global Direct Entry (GDE) customers and verify that mail classes and extra services provided in the request are supported by GDE when generating eVS labels. GDE-specific Service Type Codes (STCs) are supported within the eVS Domestic Label API (API=eVS) for use in the barcode and Shipping Services File, reference table below. eVS integrators must be flagged as GDE customers in HelpDesk Utility to access these STCs. Customers participating the GDE program should first contact their TIS representative for initial onboarding before using the eVS API.

Web Tools will verify GDE customer requests include a combination of mail class (service) and extra service supported by GDE when generating eVS Domestic labels, otherwise an error will return.

STC	Description	Class of Mail	Banner Text
124	Priority Mail - Global Direct Entry	PM	USPS TRACKING #
125	Priority Mail Signature Confirmation - Global Direct Entry	PM	USPS SIGNATURE TRACKING #
144	First Class Package Service - Global Direct Entry	FC	USPS TRACKING #
145	First Class Package Service Signature Confirmation - Global Direct Entry	FC	USPS SIGNATURE TRACKING #
626	Parcel Select - Global Direct Entry	PS	USPS TRACKING #

6.0 Appendix C

6.1 Parcel Select DE and LW service combinations

<ServiceType>	<Machinable>	<DestinationEntryFacilityType>	<SortationLevel>
PARCEL SELECT DE	TRUE	DNDC	None
PARCEL SELECT DE	TRUE	DSCF	None
PARCEL SELECT DE	TRUE	DSCF	SCF
PARCEL SELECT DE	TRUE	DSCF	5D
PARCEL SELECT DE	FALSE (Nonmachinable)	DNDC	None
PARCEL SELECT DE	FALSE (Nonmachinable)	DSCF	3D
PARCEL SELECT DE	TRUE	DDU	5D
PARCEL SELECT DE	FALSE (Nonmachinable)	DDU	5D
PARCEL SELECT DE	FALSE (Nonmachinable)	DSCF	5D
PARCEL SELECT LW	TRUE	DSCF	SCF
PARCEL SELECT LW	TRUE	DNDC	NDC (3D implied)
PARCEL SELECT LW	TRUE	None	NDC (3D implied)
PARCEL SELECT LW	TRUE	None	Mix
PARCEL SELECT LW	FALSE (Irregular)	DNDC	NDC (3D implied)
PARCEL SELECT LW	FALSE (Irregular)	DNDC	SCF (3D implied)
PARCEL SELECT LW	FALSE (Irregular)	DSCF	SCF (3D implied)
PARCEL SELECT LW	FALSE (Irregular)	None	NDC (3D implied)
PARCEL SELECT LW	FALSE (Irregular)	None	Mix
PARCEL SELECT LW	TRUE	DDU	5D
PARCEL SELECT LW	TRUE	DNDC	5D
PARCEL SELECT LW	TRUE	DSCF	5D
PARCEL SELECT LW	FALSE (Irregular)	DDU	5D
PARCEL SELECT LW	FALSE (Irregular)	DNDC	5D
PARCEL SELECT LW	FALSE (Irregular)	DSCF	5D
PARCEL SELECT LW	TRUE	DNDC	SCF (3D implied)
PARCEL SELECT LW	TRUE	DSCF	SCF (3D implied)