Retrieve all scan forms

​

A list of all ScanForm objects associated with the given API Key can also be retrieved.

Query Parameters
  • reference
    Type: string

    Filter by exact reference (e.g., merchant-defined identifier).

  • start_datetime
    Type: string

    Filter: created_at >= start_datetime (ISO8601).

  • end_datetime
    Type: string

    Filter: created_at <= end_datetime (ISO8601).

  • page
    Type: integer

    Page number (page-based pagination). If present, before_id/after_id are ignored.

  • before_id
    Type: string

    Cursor: return records created before this id (used when page is NOT provided).

  • after_id
    Type: string

    Cursor: return records created after this id (used when page is NOT provided).

  • summary
    Type: boolean

    If true, returns a lighter summary payload (via ScanFormSummary serializer).

Responses
  • application/json
  • 401

    Unauthorized request

Request Example for get/scan_forms
curl 'https://api.test.vesyl.com/v2/scan_forms?reference=SCAN123&start_datetime=2024-01-01T00%3A00%3A00Z&end_datetime=2024-12-31T23%3A59%3A59Z&page=1&before_id=sf_001&after_id=sf_050&summary=true' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "scan_forms": [
    {
      "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
    }
  ],
  "has_more": false,
  "total_count": 42
}

Scan forms retrieved successfully