Create a USPS SCAN Form

HTTP Request

POST /v1/manifests

Summary

This operation creates a USPS SCAN form (Shipment Confirmation Acceptance Notice) that combines all trackable shipments into a single form with a single bar code. If there are shipments belonging to different induction postal codes, the operation generates a multi-page form with one bar code per page.

When a carrier scans the form’s barcode, all shipments for that barcode receive an Acceptance event from USPS.

Note: To create a PMOD manifest, please instead see Create a Manifest for PMOD Shipments.

Things to Consider

  1. USPS shipments with the ADD_TO_MANIFEST shipment option set to true are eligible for inclusion in a SCAN form.

  2. To create a SCAN form for the current day, you must issue the Create Manifest request before 8 p.m. local time. If you issue the Create Manifest request after 8 p.m., you must assign the next day’s date in the submissionDate field. For more information, see What are the cutoff times for USPS shipments and manifests?

  3. If an eligible shipment is not included in a SCAN form by 6 a.m. UTC/GMT the next calendar day, it is instead auto-manifested. Shipments, once manifested, cannot be re-manifested.

    Note: To prevent a shipment from being auto-manifested, set the shipment’s FUTURE_SHIPMENT_DATE option when creating the shipment. For details, see Can I choose to manifest a shipment at a later date?

  4. Up to 7000 shipments can be included in a single Create Manifest request.

  5. You can add shipments to the SCAN form by specifying Shipper ID, tracking numbers, or both:

    • If you specify Shipper ID, the form will include all eligible shipments created with that Shipper ID. To specify Shipper ID, add the SHIPPER_ID parameter to the parameters array.
    • If you specify tracking numbers, the form will include all eligible shipments with those tracking numbers. To specify tracking numbers, use the parcelTrackingNumbers array.

    Note: If you specify both Shipper ID and tracking numbers, ensure the tracking numbers belong to the Shipper ID or the API will return an error.

  6. You can filter further by specifying an inductionPostalCode. When specified, the inductionPostalCode value in the manifest request must match the rates.inductionPostalCode value of the shipment. If a shipment has no rates.inductionPostalCode, the value in the manifest request must match the shipment’s fromAddress.postalCode.

    If you specify an inductionPostalCode in the manifest request, only shipments that meet the above criteria are included in the manifest.

  7. If a manifest request contains shipments with different inductionPostalCode values, then a multi-page manifest is created, with one inductionPostalCode value per page. The pages are accessed via a single PDF.

  8. The following USPS shipments cannot be added to the SCAN form:

    • First-Class Mail Flats (Service ID: FCM, Parcel Type: FLAT)
    • First-Class Mail Letters (Service ID: FCM, Parcel Type: LETTER)
    • Scan-Based Return Labels
  9. The following address fields are required in the fromAddress object:

    • addressLines
    • postalCode
    • countryCode
  10. The MANIFEST_TYPE parameter is not required. It can be either left out or set to NORMAL.

  11. USPS SCAN forms retrieved through URLs (i.e., documents.contentType is set to URL) are available for 24 hours after creation.

Request URIs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/manifests
Production: https://api.pitneybowes.com/shippingservices/v1/manifests

Request Headers

Name
Description
Authorization Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type Required. The media type of the request entity. Set this to application/json.
X-PB-TransactionId

Required. A unique identifier for the transaction, up to 25 characters.

Important: You must ensure this is a unique id.

X-PB-UnifiedErrorStructure Recommended. Set this to true to use the standard error object if an error occurs.

Request / Response Elements

The API call sends and receives a Manifest Object. The following table describes all possible fields in a Manifest Object.

Important

Some fields in the Manifest Object might not apply to your operation and are marked accordingly.

Name Data Type Description
carrier String

Required. The carrier to which the manifest applies.

For some operations, this field is not present in the response.

Valid values:

  • USPS
  • NEWGISTICS. PB Standard. This value is valid only in a Create Manifest request.
  • PBPresort. This value is valid only in a Create Manifest request.
submissionDate String Required. The date the shipments are to be tendered to the carrier, entered as YYYY-MM-DD.
fromAddress Address Object

Conditional. The shipment origin address.

Required for:

inductionPostalCode String

Conditional. Postal code where the shipments are tendered to the carrier.

This field does not apply to PB Standard manifests.

parcelTrackingNumbers Array[String] Identifies shipments by their tracking numbers. List one or more shipment tracking numbers, separated by commas.
parameters Array[Object]

Conditional. Each object in the array defines a different manifest parameter. This field is used only in the request and is not returned in the response.

Required for PB Standard manifests (closeouts).

        name String The name of the manifest parameter.
        value String The value of the manifest parameter.
manifestId String

RESPONSE ONLY. The unique manifest ID. This field is not returned for APAC Services.

This field is not returned for APAC Services.

manifestTrackingNumber String RESPONSE ONLY, USPS Only. The manifest tracking number.
documents Array[Documents Object]

RESPONSE ONLY. The manifest.

This field is not returned for a PB Standard manifest.

Sample Request

curl -X POST .../v1/manifests \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-H "X-PB-UnifiedErrorStructure: true" \
-d '
{
    "carrier": "USPS",
    "submissionDate": "2019-05-31",
    "fromAddress": {
        "company": "Supplies",
        "name": "John Smith",
        "phone": "203-000-0000",
        "email": "john@example.com",
        "residential": false,
        "addressLines": [
            "27 Waterview Drive"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US"
    },
    "inductionPostalCode": "06484",
    "parcelTrackingNumbers": [
        "9405509898641490245732",
        "9405809898644002256241",
        "9405809330641259071919",
        "9405809898710929474111"
    ],
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

Sample Response

{
    "carrier": "USPS",
    "submissionDate": "2019-05-31",
    "fromAddress": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "company": "Supplies",
        "name": "John Smith",
        "phone": "203-000-0000",
        "email": "john@example.com",
        "residential": false
    },
    "inductionPostalCode": "06484",
    "parcelTrackingNumbers": [
        "9405509898641490245732",
        "9405809898644002256241",
        "9405809898710929474111"
    ],
    "manifestId": "9475709899581000182251",
    "manifestTrackingNumber": "9475709899581000182251",
    "documents": [ {
        "type": "MANIFEST",
        "contentType": "URL",
        "contents": "https://.../scanform/7fc8950380d7437287692d0d3a8ddb8b.pdf"
    } ],
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}

Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.