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.
All Shipments must belong to the same carrier account.
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

ScanForm object

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

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_244b6b0b1487472db12dcdfb2622ec8d",
  "object": "ScanForm",
  "created_at": "2025-05-09T20:40:04Z",
  "updated_at": "2025-05-09T20:40:04Z",
  "tracking_codes": [
    "9405500208303109884151"
  ],
  "address": {
    "id": "adr_c8c8ddad2d1511f0b56e3cecef1b359e",
    "object": "Address",
    "created_at": "2025-05-09T20:40:03+00:00",
    "updated_at": "2025-05-09T20:40:03+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/20250509/e8edaa9a23e2044386ae61411cf7227014.pdf",
  "form_file_type": null,
  "batch_id": "batch_b35046236c8c4740accf6ed173b64964",
  "confirmation": null
}

Create a ScanForm

A ScanForm can be created in two ways:

Create a ScanForm for Shipments directly
Create a ScanForm for a Batch of Shipments

Note: A ScanForm can only include shipments from one carrier account. Shipments from different carrier accounts require separate ScanForms.

Note: A Batch is created in the background for Shipments as an intermediate process to creating ScanForms. A ScanForm can be created for one or more Shipments. It is recommended to keep each batch under 1,000 shipments. This best practice helps avoid timeout errors during the batch buying process.

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

Request Parameters

shipments

i.e. [Shipment, Shipment, ...]

POST /scan_forms

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_244b6b0b1487472db12dcdfb2622ec8d",
3  "object": "ScanForm",
4  "created_at": "2025-05-09T20:40:04Z",
5  "updated_at": "2025-05-09T20:40:04Z",
6  "tracking_codes": ["9405500208303109884151"],
7  "address": {
8    "id": "adr_c8c8ddad2d1511f0b56e3cecef1b359e",
9    "object": "Address",
10    "created_at": "2025-05-09T20:40:03+00:00",
11    "updated_at": "2025-05-09T20:40:03+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/20250509/e8edaa9a23e2044386ae61411cf7227014.pdf",
32  "form_file_type": null,
33  "batch_id": "batch_b35046236c8c4740accf6ed173b64964",
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_78cee658be9c466192bb84c8d133159d",
5      "object": "ScanForm",
6      "created_at": "2025-05-09T20:40:06Z",
7      "updated_at": "2025-05-09T20:40:06Z",
8      "tracking_codes": ["9405500208303109884168"],
9      "address": {
10        "id": "adr_c9b1e7bd2d1511f093deac1f6bc539aa",
11        "object": "Address",
12        "created_at": "2025-05-09T20:40:04+00:00",
13        "updated_at": "2025-05-09T20:40:04+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/20250509/e85a43a1ec7a9a4f5ebd2bc09ae4327886.pdf",
34      "form_file_type": null,
35      "batch_id": "batch_dc274421751b435b9108b58095ba445c",
36      "confirmation": null
37    }
38  ],
39  "has_more": true
40}

Retrieve a ScanForm

Retrieve a ScanForm by its id.

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_78cee658be9c466192bb84c8d133159d",
3  "object": "ScanForm",
4  "created_at": "2025-05-09T20:40:06Z",
5  "updated_at": "2025-05-09T20:40:06Z",
6  "tracking_codes": ["9405500208303109884168"],
7  "address": {
8    "id": "adr_c9b1e7bd2d1511f093deac1f6bc539aa",
9    "object": "Address",
10    "created_at": "2025-05-09T20:40:04+00:00",
11    "updated_at": "2025-05-09T20:40:04+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/20250509/e85a43a1ec7a9a4f5ebd2bc09ae4327886.pdf",
32  "form_file_type": null,
33  "batch_id": "batch_dc274421751b435b9108b58095ba445c",
34  "confirmation": null
35}