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, then a multi-page form is generated automatically, with one bar code per page. When the carrier scans a barcode, all the manifested shipments receive an Acceptance event from USPS.

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

Things to Consider

  1. USPS shipments with the ADD_TO_MANIFEST option set to true are eligible for inclusion in the manifest (SCAN Form).

  2. A shipment is eligible for inclusion both on and before its shipment date.

  3. If an eligible shipment is not included in a manifest by 4 a.m. GMT the next calendar day, it is automatically manifested.

  4. Up to 5000 shipments can be included in a single manifest request.

  5. Shipments, once manifested, cannot be re-manifested.

  6. You can add shipments to the manifest 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. Specify tracking numbers in 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.

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

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

  9. 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
  10. When issuing this API call, the MANIFEST_TYPE manifest 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 Data Type Description
Authorization String Required. OAuth token generated using the Generate an OAuth Token API.
Content-Type String Required. The media type of the request entity. Set this to application/json.
X-PB-TransactionId String

A unique identifier for the manifest, up to 25 characters.

Important: You must ensure this is a unique id.

Request / Response Elements

The API call sends and receives a manifest object. The table below describes all the elements in a manifest object. Some fields might not apply to your operation.

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 (applicable only if creating a manifest)
  • PBPresort (applicable only if creating a manifest)
submissionDate String

Required. The date the shipments are tendered to the carrier. The time must be in GMT/UTC and in one of the following formats:

  • YYYY-MM-DD
  • YYYY-MM-DD HH:mm:ss
  • YYYY-MM-DD HH:mm:ss.SSS
fromAddress address object Required. The shipment origin address.
inductionPostalCode String

Postal code where the shipments are tendered to the carrier.

Note: Not applicable to Newgistics manifests.

parcelTrackingNumbers Array[String]

Identifies shipments by their tracking numbers. List one or more shipment tracking numbers, separated by commas.

Note: Not applicable to Newgistics manifests.

parameters Array[Object] 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.
        name String The name of the manifest parameter.
        value String The value of the manifest parameter.
manifestId String Response Only. The unique manifest ID.
manifestTrackingNumber String Response Only. The manifest tracking number.
documents Array[documents object]

Response Only. The manifest.

Note: Not returned for a Newgistics 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>" \
-d '
{
    "carrier": "usps",
    "submissionDate": "2017-05-31",
    "fromAddress": {
        "company": "Pitney Bowes Inc.",
        "name": "John Public",
        "phone": "203-555-5555",
        "email": "john.publica@example.com",
        "residential": true,
        "addressLines": [
            "27 Waterview Drive"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US"
    },
    "inductionPostalCode": "06484",
    "parcelTrackingNumbers": [
        "9405509898641490245732",
        "9405809898644002256241",
        "9405809330641259071919",
        "9405809898710929474111"
    ],
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "88888888"
    } ]
}'

Sample Response

{
    "carrier": "usps",
    "submissionDate": "2017-05-31",
    "fromAddress": {
        "addressLines": [
            "27 Waterview Dr"
        ],
        "cityTown": "Shelton",
        "stateProvince": "CT",
        "postalCode": "06484",
        "countryCode": "US",
        "company": "Pitney Bowes Inc.",
        "name": "John Public",
        "phone": "203-555-1430",
        "email": "john.publica@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": "88888888"
    } ]
}

Error Codes

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