1.0 Introduction

This document contains a Reference Guide to the SCAN API. See the Developer's Guide to learn the administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also contains information on testing and troubleshooting. 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. 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.

1.1 Before you get started:

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Web Tools Technical Documentation Page.

2.0 SCAN API

2.1 Overview

The SCAN API allows integrators to consolidate multiple domestic and international labels and custom forms through one Electronic File Number (EFN) and physical SCAN Form (PS Form 5630 or 3152). The API operates as follows:

Individual API requests for shipping labels, for example through the eVS API, must include HoldForManifest=”Y” in order to be eligible for inclusion on a SCAN Form. More information on available label APIs can be found on the Web Tools documentation website.
“Held for manifest” labels can then be provided in a SCAN API request.

3. A “close manifest” request (i.e <CloseManifest>) can be used through the SCAN API to automatically close any labels generated by that user through Web Tools domestic and international shipping label APIs still being “held for manifest.” The <CloseManifest> tag allows for two options:

· “ALL” – will close all labels for the submitted USERID regardless of the SHIPDATE on the individual labels.

· “SHIPDATE” will close all the labels for the submitted USERID that have the <Shipdate> tag from the label API request matching the value of the <MailDate> tag in the SCAN API request.

Note: The <MaxPackagesExceeded> field indicates that over 1,000 barcodes were submitted for the given user ID. If these conditions are not met, the tag will not return in the response. Users who do receive this tag in the response, should submit another request for the given user ID to ensure all outstanding records being held are closed. This field is only eligible to return when <CloseManifest> option is included in the request with either an “ALL” or “SHIPDATE” enumeration indicated.

Considerations to label grouping compatibility for the Web Tools SCAN API:

Labels you intend to add to a SCAN form must first be created through Web Tools label APIs

2. The label and SCAN Form requests must all be to the same environment (if you are creating test labels in the stg- environment, then you would need to request the SCAN form in the same stg- environment)

3. Labels that have been canceled or already manifested are not eligible to be added to a SCAN Form.

4. The labels must be requested with HoldForManifest=”Y”

5. The MailDate in the SCAN API request must match the ShipDate of the individual labels created through the label APIs

6. The origin FromZip5 (or POZipCode when provided) in the labels request must match the FromZip5 (or EntryFacility when provided) in the SCAN API request

Label must NOT be created with the “Certify” label APIs (e.g. eVSCertify) Note: Certify requests are for test purposes and will not be valid since they will not be saved in the system (and therefore will not be found in order to add to a SCAN form)

Note: The SCAN API can contain no more than 1,000 package barcodes in a single request. If exceeded, 'Total PackageDetail items exceeded 1000.’ error will return”

In order to generate 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 (no destination entry or presort)
Requires enrollment and new Mailer IDs (MIDs) and permits
Supports domestic/international/apo/fpo/dpo/US Territories

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.

2.1.1 API Signature

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

2.2 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
SCANRequest	Required	API=SCAN	(Alias)
SCANRequest / USERID	Required	This attribute specifies your Web Tools user ID. See the Developer's Guide for information on obtaining your USERID. For Example: USERID="XXXXXXX"	NMTOKEN
SCANRequest / PASSWORD	Required	This attribute specifies your Web Tools password. See the Developer's Guide for information on your Password. For Example: PASSWORD="XXXXXXX"	NMTOKEN
SCANRequest / Option	Optional	Groups form information	(Group)
SCANRequest / Option / Form	Optional	Designates desired label option selected by customer. Enter one of the valid entries: ‘3152’ generates PS Form 3152. ‘5630’ generates PS Form 5630. For example: <Form>3152</Form>	String	Enumeration= · 3152 · 5630
SCANRequest / FromName	Required	Name of sender. Example: <FromName>Joe Smith</FromName>	String
SCANRequest / FromFirm	Optional	Company name. Example: <FromFirm>ABC Corp.</FromFirm>	String
SCANRequest / FromAddress1	Optional	From address line 1. Denote apartment or suite number. Example: <FromAddress1>Apt. 3C</FromAddress1>	String
SCANRequest / FromAddress2	Required	From address line 2. Denote street/structure number. Example: <FromAddress2>475 L’Enfant Plaza SW</FromAddress2>	String
SCANRequest / FromCity	Required	From city. Example: <FromCity>Greenbelt</FromCity>	String
SCANRequest / FromState	Required	From state. Example: <FromState>MD</FromState>	String
SCANRequest / FromZip5	Required	From ZIP Code. Must be a valid ZIP5 Code. Example: <FromZip5>20770</FromZip5>	String
SCANRequest / FromZip4	Optional	From ZIP Code+4. Example: <FromZip4>1234</FromZip4>	String
SCANRequest / Shipment	Required once, repeating up to unbounded times	Groups shipment information	(Group)
SCANRequest / Shipment / PackageDetail	Optional, repeating up to unbounded times	Groups package detail information	(Group)
SCANRequest / Shipment / PackageDetail / PkgBarcode	Required	Individual package barcodes. Example: <PkgBarcode>4202026091XXXXXXXXXXXXXXX</PkgBarcode> Note: The SCAN API can contain no more than 1,000 package barcodes in a single request. If exceeded, 'Total PackageDetail items exceeded 1000.’ error will return”	String
SCANRequest / Shipment / PackageDetail / SpecialService	Optional, repeating up to unbounded times	FOR FUTURE USE. Groups extra service information.	(Group)
SCANRequest / Shipment / PackageDetail / SpecialService / SpcServCode	Required	FOR FUTURE USE. If present, must be <SpcServFee>. From Extra Service Code table. Example: <SpcServCode>01</SpcServCode>	String
SCANRequest / Shipment / PackageDetail /SpecialService/ SpcServFee	Required	FOR FUTURE USE. Fee for Extra Service. Example: <SpcServFee>00275</SpcServFee>	String
SCANRequest / Shipment / PackageDetail / EMail	Optional	FOR FUTURE USE. Email address of acceptance scan event recipient. Example: <EMail>john.smith@abc.com</EMail>	String
SCANRequest / CloseManifest	Optional, mutually exclusive with the <Shipment> tag	Used to include all labels for the submitted UserID. There are two values: “ALL” will close all labels for the submitted USERID. “SHIPDATE” will close all the labels for the submitted USERID that have the <Shipdate> tag matching the value in the <MailDate> tag. Note: When <CloseManifest> is indicated in the request, the following two response fields are eligible to return if conditions are met: · <MaxPackagesExceeded> · <MaxLabelsExceeded>	Boolean	Enumeration= · ALL · SHIPDATE
SCANRequest / MailDate	Required	Date of mailing/Carrier Pickup. This denotes date mail to be tendered to Postal Service. YYYYMMDD format. Example: <MailDate>20060103</MailDate>	String
SCANRequest / MailTime	Required	Time of mailing/Carrier Pickup. This is an approximation. This denotes time of mail to be tendered to Postal Service. HHMMSS (24 hour) format. Example: <MailTime>143000</MailTime>	String
SCANRequest / EntryFacility	Required	ZIP Code of Postal Service facility. Populate/required only if different from <FromZip5>. Example: <EntryFacility>07067</EntryFacility>	String
SCANRequest / ImageType	Required	The form image format desired. Enter one of the valid entries: Example: <ImageType>TIF</ImageType>	String	Enumeration= · TIF · PDF · NONE
SCANRequest / CustomerRefNo	Optional	Arbitrary number for customers own tracking or inventory systems, does not print to form or manifest with Product Tracking. May be any combination of alpha and numeric characters, up to a maximum of 30. Example: <CustomerRefNo>123456</CustomerRefNo>	String
SCANRequest / CarrierPickup	Optional	FOR FUTURE USE.	Boolean	Default=false
SCANRequest	Required		(Alias)

2.2.1 Sample Request

Request: SCAN

</Option>

<FromName>Josh Webster</FromName>

<FromFirm>Postal Service</FromFirm>

<FromAddress1>Suite 999</FromAddress1>

<FromAddress2>901 D Street SW</FromAddress2>

<FromCity>Washington</FromCity>

<PkgBarcode>4207823892058XXXXXXXXXXXXXXX</PkgBarcode>

</PackageDetail>

</Shipment>

</SCANRequest>

Request: SCAN with Close Manifest option

</Option>

<FromName>Lina Smith</FromName>

<FromAddress2>4470 Oakdale Crescent Ct</FromAddress2>

<FromCity>Fairfax</FromCity>

</SCANRequest>

2.3 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
SCANResponse	Required once		(Alias)
SCANResponse / SCANFormNumber	Required once	Electronic File Number.	Integer
SCANResponse / SCANFormImage	Required once	Encoded image of PS Form 3152 or PS Form 5630.	Base64Binary
SCANResponse / MaxPackagesExceeded	Optional	This field indicates that over 1,000 barcodes were submitted for the given user ID. When the number of barcodes submitted is greater than 1,000, then the <MaxPackagesExceeded> tag will return with a value of “true”. If these conditions are not met, the tag will not return in the response. Users who do receive this tag in the response, should submit another request for the given user ID to ensure all outstanding records being held are closed. This field is only eligible to return when <CloseManifest> option is included in the request with either an “ALL” or “SHIPDATE” enumeration indicated. For example: <MaxPackagesExceeded>true </MaxPackagesExceeded>	Boolean	Enumeration= · true
SCANResponse / MaxLabelsExceeded	Optional	This field indicates that over 10 SCAN forms were returned in the response due to multiple entry zip codes and/or ship dates requested by the given user ID. If these conditions are not met, the tag will not return in the response. Users who do receive this tag in the response, should submit another request for the given user ID to ensure all outstanding records being held are closed. This field is only eligible to return when the <CloseManifest> option is included in the request with either an “ALL” or “SHIPDATE” enumeration indicated. For example: <MaxLabelsExceeded>true<MaxLabelsExceeded>	Boolean	Enumeration= · true
SCANResponse			(Alias)

2.3.1 Sample Response

Response: SCAN/SCAN with <CloseManifest> included in request

<SCANFormNumber>92750XXXXXXXXXXXXXXXXX</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA -- suppressed --

</SCANFormImage>

</SCANResponse>

Response: SCAN when packages exceed 1,000

<SCANFormNumber>92750XXXXXXXXXXXXXXXXX</SCANFormNumber>