Create a PB Expedited Manifest (USPS SCAN Form)¶

HTTP Request¶

POST /v1/manifests

Summary¶

This operation creates a USPS^® SCAN form (Shipment Confirmation Acceptance Notice) that combines all trackable PB Expedited Delivery shipments into a single form with a single bar code. When the carrier scans the barcode, all shipments for that barcode receive an Acceptance event from USPS. If the SCAN form includes shipments from multiple different induction postal codes, this operation generates a multi-page form with one bar code per page.

Note

To create a PB Standard Manifest (Closeout), click here.

Considerations¶

PB Expedited Delivery shipments with the ADD_TO_MANIFEST shipment option set to true are eligible for inclusion in a SCAN form.
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?
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?
Up to 7000 shipments can be included in a single Create Manifest request.
You can add shipments to the SCAN form by specifying the Shipper ID, the tracking numbers, or both:
- If you specify the 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 the Shipper ID and the tracking numbers, ensure the tracking numbers belong to the Shipper ID or the API will return an error.
You can filter further by specifying an origin ZIP value in the manifest request’s inductionPostalCode field. When specified, the origin ZIP value must match the shipment’s rates.inductionPostalCode field, if present, or otherwise match the shipment’s fromAddress.postalCode field. Only shipments that match the origin ZIP value are included in the manifest.
If a manifest request contains shipments with multiple origin ZIP values, a multi-page manifest is created, with one origin ZIP value (inductionPostalCode value) per page. The pages are accessed via a single PDF.
The API will throw an error if the manifest request contains shipments with 26 or more different origin ZIP values. The origin ZIP value comes from the shipment’s rates.inductionPostalCode field, if specified, or otherwise from the shipment’s fromAddress.postalCode field.
The following PB Expedited 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)
- PB Expedited Returns
USPS SCAN forms retrieved through URLs are available for 24 hours after creation.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/manifests
Production: https://shipping-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. The following characters are allowed: letters, numbers, hyphens (`-`), and underscores (`_`). Important: 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¶

Required fields are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name	Data Type	Description
carrier	String	Required. Set this to: `USPS`
submissionDate	String	Required. The date the shipments are to be tendered to the carrier, entered as `YYYY-MM-DD`.
fromAddress	Address Object	Required. The shipment origin address. The following address fields are required: `addressLines` `postalCode` `countryCode`
inductionPostalCode	String	Postal code where the shipments are tendered to the carrier.
parcelTrackingNumbers	Array[String]	Identifies shipments by their tracking numbers. List one or more tracking numbers, separated by commas. Enter each tracking number as a separate String.
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. The following parameters are available: `SHIPPER_ID`: Adds shipments by Shipper ID. Specify the Shipper ID that was used to create the shipments. `MANIFEST_TYPE`: The manifest type for a PB Expedited manifest is `NORMAL`, which is the default setting. You do not need to specify this parameter in your API call.
parameters.name	String	The name of the manifest parameter.
parameters.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.

Sample Requests¶

See the following sample manifest requests:

PB Expedited SCAN Form by Shipper ID
PB Expedited SCAN Form by Tracking Numbers

PB Expedited SCAN Form by Shipper ID¶

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": "2021-07-23",
    "fromAddress": {
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "postalCode": "36830-6433",
        "countryCode": "US"
    },
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ]
}'

Sample Response¶

{
    "carrier": "USPS",
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../scanform/b2f4a1ad0e7046669540562f73da79e8.pdf",
        "type": "MANIFEST"
    } ],
    "fromAddress": {
        "company": "",
        "name": "",
        "residential": false,
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US"
    },
    "manifestId": "9475709899581000182251",
    "manifestTrackingNumber": "9475709899581000182251",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "submissionDate": "2021-07-23"
}

PB Expedited SCAN Form by Tracking Numbers¶

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": "2021-07-23",
    "fromAddress": {
        "addressLines": [
            "545 Market St"
        ],
        "postalCode": "94105",
        "countryCode": "US"
    },
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "parcelTrackingNumbers": [
        "9405509898641492021204",
        "9405509898641492021150",
        "9405509898641492021211"
    ]
}'

Sample Response¶

{
    "carrier": "USPS",
    "documents": [ {
        "contentType": "URL",
        "contents": "https://.../scanform/b3368cba764a46f9b368aa0bc9483105.pdf",
        "type": "MANIFEST"
    } ],
    "fromAddress": {
        "company": "",
        "name": "",
        "residential": false,
        "addressLines": [
            "545 Market St"
        ],
        "cityTown": "San Francisco",
        "stateProvince": "CA",
        "postalCode": "94105",
        "countryCode": "US"
    },
    "manifestId": "9475709899581009777182",
    "manifestTrackingNumber": "9475709899581009777182",
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    } ],
    "parcelTrackingNumbers": [
        "9405509898641492021204",
        "9405509898641492021150",
        "9405509898641492021211"
    ],
    "submissionDate": "2021-07-23"
}

Error Codes¶

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.