Create a scan form

​

A ScanForm can be created in two ways:

  1. Create a ScanForm for Shipments directly
  2. 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.

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

Body
required
application/json
    • reference
      Type: string
      required
    • carrier
      Type: string | null
    • up_to_time
      Type: string | nullFormat: date_time
Responses
  • application/json
  • application/json
  • 401

    Unauthorized request

  • application/json
Request Example for post/scan_forms
curl https://api.test.vesyl.com/v2/scan_forms \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "reference": "SCAN123",
  "carrier": "USPS",
  "up_to_time": "2025-10-02T19:27:57Z"
}'

{
  "id": "sf_b70df1b68703eb774f13001f4209e5ef",
  "created_at": "2025-10-02T03:18:54Z",
  "updated_at": "2025-10-02T03:19:12Z",
  "object": "ScanForm",
  "status": "created",
  "tracking_codes": [
    null
  ],
  "address": {
    "id": "adr_919e3e3de9134e78bc8e050e963ad821",
    "created_at": "2025-10-02T19:27:57Z",
    "updated_at": "2025-10-02T19:27:57Z",
    "object": "Address",
    "street1": "1 Market St",
    "street2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "name": "John Doe",
    "company": null,
    "phone": "2122341400",
    "email": "support@wizmo.com",
    "residential": null,
    "verifications": {
      "verify": [
        "delivery"
      ],
      "delivery": {
        "errors": [],
        "details": {
          "latitude": 42.15259,
          "longitude": -83.67457,
          "time_zone": "America/Detroit"
        },
        "success": true
      },
      "smarty": {
        "success": true,
        "usps_eligible": true,
        "recommended_address": {
          "object": "Address",
          "street1": "1 Market St",
          "street2": "uite 400",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94104",
          "country": "US",
          "residential": null
        },
        "warnings": []
      }
    }
  },
  "message": "",
  "form": "bugstrin",
  "form_file_type": "csv",
  "form_url": "https://api.test.vesyl.com/rails/active_storage/blobs/proxy/.../scan_form.csv",
  "batch_id": "batch_0f998a51d4058e341e64f25335261f85",
  "reference": null,
  "confirmation": null,
  "carrier": "USPS",
  "num_shipments": 126
}

Scan form created successfully