Manifest Guide

This guide will explain what manifests are, why they are important, and how to create them with the EasyPost API.

A shipping manifest is a crucial checklist of packages that are ready for pickup by a carrier. They act as an advance notice of the packages that the driver or carrier agent has to pick up from your premises. Some carriers will require a manifest before their end-of-day pickups. Even if your carrier doesn't, it's still a good idea to manifest your shipments so you can hand the carrier a single form that accounts for all of the shipments being picked up.

In EasyPost, you can create a manifest using the ScanForm object. When you create Shipment or Batch objects for your individual packages, you can include them into the ScanForm object. There are a few rules that you have to follow when creating a ScanForm

  • Refunded Shipments cannot be added.
  • Each Shipment must have the same origin address.
  • Shipments must all be dated (using the label_date option) on or after the date of the form's generation.
  • Shipments cannot be added to more than one ScanForm
  • Shipments must be provided in the form of an array.

There are eleven attributes in the ScanForm object that provide all the information regarding your manifest:

  • id: The ID number of the ScanForm, you should record this for documentation purposes
  • object: The object, which in this case, should always read "ScanForm".
  • status: Status of the ScanForm. Possible values include "creating", "created", and "failed".
  • message: The field where we explain any possible errors.
  • address: The origin address of the shipments.
  • tracking_codes: Tracking codes associated with all shipments in the ScanForm
  • form_url: URL of the document.
  • form_file_type: File format of the document.
  • batch_id: The ID of the associated Batch, if you decided to Batch your shipments before inserting them into the ScanForm. To learn more about Batches, see our Related Links.
  • created_at: Timestamp of the ScanForm creation.
  • updated_at: Timestamp of the latest ScanForm update.

Here is an example of creating a ScanForm and listening for when the asynchronous job is complete using webhooks:

Step 1: Create a ScanForm

This is a simple example of creating a ScanForm, but many users will first create a Batch first, see the Batches Guide for an example of that.

Note: A Batch is created in the background for Shipments as an intermediate process to creating ScanForms. You can create a ScanForm for 1 or a group of Shipments.

Creating a ScanForm
require 'easypost'
EasyPost.api_key = "<YOUR_TEST/PRODUCTION_API_KEY>"

scan_form = EasyPost::ScanForm.create(shipments: [shipment])


    
ScanForm Response
{
   "id":"sf_5fcd15deb9d84483835ed687a73fee7d",
   "object":"ScanForm",
   "created_at":"2017-01-20T22:59:03Z",
   "updated_at":"2017-01-20T22:59:04Z",
   "tracking_codes":[
      "8888888888888888888888"
   ],
   "address":{
      "id":"adr_d5415c4f055c44169cc159d2958d768f",
      "object":"Address",
      "created_at":"2016-10-04T19:08:20Z",
      "updated_at":"2016-10-04T19:08:20Z",
      "name":"EasyPost",
      "company":null,
      "street1":"417 Montgomery Street",
      "street2":"5th Floor",
      "city":"San Francisco",
      "state":"CA",
      "zip":"94104",
      "country":"US",
      "phone":"4153334445",
      "email":"support@easypost.com",
      "mode":"test",
      "carrier_facility":null,
      "residential":null,
      "federal_tax_id":null,
      "state_tax_id":null,
      "verifications":{

      }
   },
   "status":"created",
   "message":null,
   "form_url":"https://easypost-files.s3-us-west-2.amazonaws.com/files/scan_form/20170120/27099fe01af34349821e4be06d0cdu7t.pdf",
   "form_file_type":null,
   "batch_id":"batch_6b145453b20740209ddaedef63a4a88k",
   "confirmation":null
}

Step 2: Receive Webhook

We'll send an Event to your Webhook URLs once the ScanForm is ready. Check for scan_form.created in the Event's description field. If you haven't read our Webhooks Guide it will show you how to handle those Events.

Webhook POST JSON

{
  "result": {
    "id": "sf_95b6272977fd467d995d7ea21a851c0e",
    "object": "ScanForm",
    "created_at": "2015-09-30T21:00:55Z",
    "updated_at": "2015-09-30T21:00:57Z",
    "tracking_codes": [
      "9405536897846194850412",
      "9400136897846194907281",
      "9400136897846194977529",
    ],
    "address": {
      "id": "adr_tyRwEd23",
      "object": "Address",
      "created_at": "2015-09-30T21:00:55Z",
      "updated_at": "2015-09-30T21:00:55Z",
      "name": "George Costanza",
      "company": "Vandelay Industries",
      "street1": "1 E 161st St.",
      "street2": null,
      "city": "Bronx",
      "state": "NY",
      "zip": "10451",
      "country": "US",
      "phone": null,
      "email": null,
      "mode": "test",
      "carrier_facility": null,
      "residential": null,
      "federal_tax_id": null,
      "state_tax_id": null,
      "verifications": {}
    },
    "status": "created",
    "message": null,
    "form_url": "https://easypost-files.s3-us-west-2.amazonaws.com/...2c0cb9.pdf",
    "form_file_type": null,
    "batch_id": "batch_3d3609f1b2fd4a80ba83db3b9430ebc3",
    "confirmation": null
  },
  "description": "scan_form.created",
  "mode": "test",
  "previous_attributes": {},
  "created_at": "2015-09-30T21:00:57Z",
  "pending_urls": [],
  "completed_urls": ['https://www.example.com/easypost-webhook'],
  "updated_at": "2015-09-30T21:00:57Z",
  "id": "evt_d5ba4dc704074f299ac310100f1cde26",
  "user_id": "user_e674f6db117441e5b740a8ec030b1f85",
  "status": "in_queue",
  "object": "Event"
}