Looking for the old docs? View our old docs site.
API Docs

ScanForm

A ScanForm can be created to speed up and simplify the carrier pickup process. The ScanForm is one document that can be scanned to mark all included tracking codes as "Accepted for Shipment" by the carrier. The following criteria must met before creation:

  • Refunded Shipments cannot be added.
  • Each Shipment must have the same origin_address.
  • Each Shipment must be dated (using the label_date option) on or after the date the form is generated.
  • Any given Shipment cannot be added to more than one ScanForm.
  • Existing ScanForms may not be updated with additional Shipments. If a ScanForm already exists and new Shipments need to be added, a new ScanForm must be created.
  • Shipments should be provided in the form of an array.
Endpoints
POST
/scan_forms
POST
/batches/:id/scan_form
GET
/scan_forms
GET
/scan_forms/:id

ScanForm object

id
string
Unique, begins with "sf_"
object
string
"ScanForm"
status
string

Current status. Possible values:

  • creating - The ScanForm is being created
  • created - The ScanForm has been created
  • failed - The ScanForm failed to be created
message
string
Human readable message explaining any failures
address
Address that the packages will be shipped from
tracking_codes
string array
Tracking codes included on the ScanForm
form_url
string
Url of the document
form_file_type
string
File format of the document
batch_id
string
The ID of the associated Batch. Unique, starts with "batch_".
created_at
datetime
When the ScanForm was created
updated_at
datetime
When the ScanForm was last updated
ScanForm Object
{
  "id": "sf_e79db685aecd4c7286471ff06a27a121",
  "object": "ScanForm",
  "created_at": "2024-01-24T00:07:27Z",
  "updated_at": "2024-01-24T00:07:27Z",
  "tracking_codes": [
    "9405500207552011812801"
  ],
  "address": {
    "id": "adr_8e182c46ba4c11ee8b51ac1f6bc53342",
    "object": "Address",
    "created_at": "2024-01-24T00:07:25+00:00",
    "updated_at": "2024-01-24T00:07:25+00:00",
    "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/20240124/e872ec72373078434880f49a17e5788dcc.pdf",
  "form_file_type": null,
  "batch_id": "batch_78507c9db0574b02813cf08bd52357b5",
  "confirmation": null
}

Create a ScanForm

A ScanForm can be created in two ways:

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

A ScanForm object is immutable once created. All information must be provided during creation; it cannot be modified later.

Request Parameters

id
i.e. [Shipment, Shipment, ...]
POST /scan_formsPOST /batches/:id/scan_form
1curl -X POST https://api.easypost.com/v2/scan_forms \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "shipments": [
6      {
7        "id": "shp_..."
8      },
9      {
10        "id": "shp_..."
11      }
12    ]
13  }'
Response
1{
2  "id": "sf_e79db685aecd4c7286471ff06a27a121",
3  "object": "ScanForm",
4  "created_at": "2024-01-24T00:07:27Z",
5  "updated_at": "2024-01-24T00:07:27Z",
6  "tracking_codes": ["9405500207552011812801"],
7  "address": {
8    "id": "adr_8e182c46ba4c11ee8b51ac1f6bc53342",
9    "object": "Address",
10    "created_at": "2024-01-24T00:07:25+00:00",
11    "updated_at": "2024-01-24T00:07:25+00:00",
12    "name": "EasyPost",
13    "company": null,
14    "street1": "417 Montgomery Street",
15    "street2": "5th Floor",
16    "city": "San Francisco",
17    "state": "CA",
18    "zip": "94104",
19    "country": "US",
20    "phone": "4153334445",
21    "email": "support@easypost.com",
22    "mode": "test",
23    "carrier_facility": null,
24    "residential": null,
25    "federal_tax_id": null,
26    "state_tax_id": null,
27    "verifications": {}
28  },
29  "status": "created",
30  "message": null,
31  "form_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/scan_form/20240124/e872ec72373078434880f49a17e5788dcc.pdf",
32  "form_file_type": null,
33  "batch_id": "batch_78507c9db0574b02813cf08bd52357b5",
34  "confirmation": null
35}

Retrieve all ScanForms

A list of all ScanForm objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

before_id
i.e. sf_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. sf_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
start_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.
end_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.
page_size
i.e. 20
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /scan_forms
1curl -X GET https://api.easypost.com/v2/scan_forms?page_size=5 \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "scan_forms": [
3    {
4      "id": "sf_589e52186e9249669c7806912a6ab766",
5      "object": "ScanForm",
6      "created_at": "2024-01-24T00:07:29Z",
7      "updated_at": "2024-01-24T00:07:29Z",
8      "tracking_codes": ["9405500207552011812825"],
9      "address": {
10        "id": "adr_8f5e7e74ba4c11ee8bd0ac1f6bc53342",
11        "object": "Address",
12        "created_at": "2024-01-24T00:07:28+00:00",
13        "updated_at": "2024-01-24T00:07:28+00:00",
14        "name": "EasyPost",
15        "company": null,
16        "street1": "417 Montgomery Street",
17        "street2": "5th Floor",
18        "city": "San Francisco",
19        "state": "CA",
20        "zip": "94104",
21        "country": "US",
22        "phone": "4153334445",
23        "email": "support@easypost.com",
24        "mode": "test",
25        "carrier_facility": null,
26        "residential": null,
27        "federal_tax_id": null,
28        "state_tax_id": null,
29        "verifications": {}
30      },
31      "status": "created",
32      "message": null,
33      "form_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/scan_form/20240124/e82a4cb71096604dc7bd773b1285d7e9db.pdf",
34      "form_file_type": null,
35      "batch_id": "batch_83009a1272fa48ffb1a3d29074a16960",
36      "confirmation": null
37    }
38  ],
39  "has_more": true
40}

Retrieve a ScanForm

Retrieve a ScanForm by its id.

Request Parameters

id
i.e. sf_...
Unique, starts with "sf"
GET /scan_forms/:id
1curl -X GET https://api.easypost.com/v2/scan_forms/sf_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "sf_589e52186e9249669c7806912a6ab766",
3  "object": "ScanForm",
4  "created_at": "2024-01-24T00:07:29Z",
5  "updated_at": "2024-01-24T00:07:29Z",
6  "tracking_codes": ["9405500207552011812825"],
7  "address": {
8    "id": "adr_8f5e7e74ba4c11ee8bd0ac1f6bc53342",
9    "object": "Address",
10    "created_at": "2024-01-24T00:07:28+00:00",
11    "updated_at": "2024-01-24T00:07:28+00:00",
12    "name": "EasyPost",
13    "company": null,
14    "street1": "417 Montgomery Street",
15    "street2": "5th Floor",
16    "city": "San Francisco",
17    "state": "CA",
18    "zip": "94104",
19    "country": "US",
20    "phone": "4153334445",
21    "email": "support@easypost.com",
22    "mode": "test",
23    "carrier_facility": null,
24    "residential": null,
25    "federal_tax_id": null,
26    "state_tax_id": null,
27    "verifications": {}
28  },
29  "status": "created",
30  "message": null,
31  "form_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/scan_form/20240124/e82a4cb71096604dc7bd773b1285d7e9db.pdf",
32  "form_file_type": null,
33  "batch_id": "batch_83009a1272fa48ffb1a3d29074a16960",
34  "confirmation": null
35}