SCAN API

 

 

USPS Web Tools™

Application Programming Interface

User Guide

Version 3.0 (12/1/2020)

 

 

 

 

 

 

Logo

Description automatically generated

 


 

Table of Contents

1.0      Introduction. 3

1.1      Before you get started: 3

2.0      SCAN API 3

2.1      Overview. 3

2.1.1       API Signature. 4

2.2      Request Descriptions. 4

2.2.1       Sample Request 7

2.3      Response Descriptions. 8

2.3.1       Sample Response. 9

2.3.2       PS Form 3152. 11

2.3.3       PS Form 5630. 12

 


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:

 

<ZipDestination>12345</ZipDestination>

 

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:

  1. 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.
  2. “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:

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

  1. 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:

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 ID. See the Developers Guide for information on obtaining your USERID.

For Example: <USERID=”XXXXXXXXXXXX”>

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

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

<SCANRequest USERID="XXXXXXXXXXXX">

<Option>

<Form>5630</Form>

</Option>

<FromName>Josh Webster</FromName>

<FromFirm>Postal Service</FromFirm>

<FromAddress1>Suite 999</FromAddress1>

<FromAddress2>901 D Street SW</FromAddress2>

<FromCity>Washington</FromCity>

<FromState>DC</FromState>

<FromZip5>20024</FromZip5>

<FromZip4>6129</FromZip4>

<Shipment>

<PackageDetail>

<PkgBarcode>420782389205844444444400223232</PkgBarcode>

</PackageDetail>

</Shipment>

<MailDate>20200302</MailDate>

<MailTime>120501</MailTime>

<EntryFacility/>

<ImageType>PDF</ImageType>

<CustomerRefNo>EF789URV</CustomerRefNo>

</SCANRequest>

Request: SCAN with Close Manifest option

<SCANRequest USERID="XXXXXXXXXXXX">

<Option>

<Form>5630</Form>

</Option>

<FromName>Lina Smith</FromName>

<FromFirm>Horizon</FromFirm>

<FromAddress1>Apt 949</FromAddress1>

<FromAddress2>4470 Oakdale Crescent Ct</FromAddress2>

<FromCity>Fairfax</FromCity>

<FromState>VA</FromState>

<FromZip5>22030</FromZip5>

<FromZip4/>

<CloseManifest>ALL</CloseManifest>

<MailTime>020501</MailTime>

<EntryFacility>22030</EntryFacility>

<ImageType>PDF</ImageType>

<CustomerRefNo/>

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

<SCANResponse>

<SCANFormNumber>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA -- suppressed --

</SCANFormImage>

</SCANResponse>

 

Response: SCAN when packages exceed 1,000

<SCANResponse>

<SCANFormNumber>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<MaxPackagesExceeded>true</MaxPackagesExceeded>

</SCANResponse>

 

Response: SCAN when labels exceed 1,000

<SCANResponse>

<SCANFormNumber EntryZipCode=”16901” ShipDate=”11/22/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”18702” ShipDate=”11/22/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”18704” ShipDate=”11/22/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”90210” ShipDate=”11/22/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”16901” ShipDate=”11/17/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”16901” ShipDate=”11/18/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”16901” ShipDate=”11/19/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”16901” ShipDate=”11/20/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”16901” ShipDate=”11/21/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<SCANFormNumber EntryZipCode=”18702” ShipDate=”11/17/2020”>CS201009141406094670660949S</SCANFormNumber>

<SCANFormImage>SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBA – over 1000 suppressed --

</SCANFormImage>

<MaxLabelsExceeded>true</MaxLabelsExceeded>

</SCANResponse>

2.3.2   PS Form 3152

PS Form 3152 Image Graphic

Figure 1: Scan PS Form 3152

2.3.3   PS Form 5630

PS Form 5630 Image Graphic

Figure 2: Scan PS Form 5630