Scan Reports APIs

This section describes the APIs used by the App flow. These endpoints allow clients to: Check the processing status of one or more scans. Fetch on-demand analytical reports for a given scan.

1. Fetch Scan Statuses

Endpoint

POST /mobilesdkapi/facing/scan-statuses

Description

Returns the current processing status and metadata for one or more scans. This is typically used to show whether a scan is still in progress, completed, or failed, and to expose basic capture metadata.

Authentication

This endpoint requires a valid access token.

Headers:

x-pensa-access-token: <access_token>
X-Cognito-Username: <app_username>

Request

Request body

{
  "scan_ids": [1234, 5678]
}

• scan_ids (array, required): List of scan IDs whose status you want to query.

Response

Success response (200)

{
  "data": [
    {
      "capture_duration_secs": 5,
      "completed": "2025-12-11T18:31:27.969581",
      "created": "2025-12-11T18:12:55.045122",
      "fast_completed": "2025-12-11T18:21:13.370119",
      "fast_status": "COMPLETE",
      "id": 43338,
      "scan_timestamp": "2025-12-11T18:12:45.336000",
      "scanner_id": 37,
      "shelf_scan_period_id": 31565,
      "status": "COMPLETE"
    }
  ]
}

Field reference

Top-level

• data (array): List of scan status items.

ScanStatusItem fields (NEW MODEL)

• id (int): Scan ID.

• status (string): Final processing status (for example, COMPLETE).

• fast_status (string): Fast-pipeline status (for example, COMPLETE).

• created (string): Timestamp when the scan record was created.

• scan_timestamp (string): Timestamp when the scan was captured.

• scanner_id (int): Identifier of the scanner device.

• shelf_scan_period_id (int): Shelf scan period identifier.

• fast_completed (string): Timestamp when the fast pipeline completed.

• completed (string): Timestamp when the full pipeline completed.

• capture_duration_secs (int): Total capture duration (in seconds).

---

2. Fetch On-Demand Reports

Endpoint

POST /mobilesdkapi/facing/reports-on-demand

Description

Returns on-demand analytical reports for a given scan.

Authentication

This endpoint also requires a valid access token.

Headers:

x-pensa-access-token: <access_token>
X-Cognito-Username: <app_username>

Request

Request body

{
  "scan_id": 1234,
  "report_types": ["ITEMS_SEEN", "OOS"]
}

• scan_id (int, required): ID of the scan you want to fetch reports for.

• report_types (array, required): List of report types to return.

  • FACINGS_SEEN

  • FULL_FACINGS

  • FULL_FACINGS_AND_PRODUCT_POSITIONS

  • ITEMS_SEEN

  • NEW_PRODUCTS

  • OOS

  • PRODUCT_POSITIONS

Response

Success response (200)

A simplified example response:

{
  "data": {
    "ITEMS_SEEN": { //Or whatever report you requested will be returned under that name.
      "project_report_name": "SF Item seen report",
      "project_report_id": 456,
      "project_name": "Sample Project",
      "project_id": 999,
      "scan_id": 1234,
      "report": {
        "product_list": [
          {
            "brand": "Brand A",
            "brand_id": 10,
            "category": "Beverages",
            "category_id": 20,
            "manufacturer": "Manufacturer X",
            "manufacturer_id": 30,
            "product": "Product A 1L",
            "product_id": 1001,
            "upc": "1234567890123"
          },
          {
            "brand": "Brand B",
            "brand_id": 19,
            "category": "Snacks",
            "category_id": 29,
            "manufacturer": "Manufacturer Y",
            "manufacturer_id": 39,
            "product": "Product B Chips",
            "product_id": 1002,
            "upc": "2345678901234"
          }
        ]
      }
    }
  }
}

Field reference

Top-level

• data (object): Map of report type

Report wrapper

• project_report_name (string): Readable report name.

• project_report_id (int): Internal identifier of the report definition.

• project_name (string): Name of the project associated with the scan.

• project_id (int): Project identifier.

• scan_id (int): Scan identifier the report belongs to.

• report (object): Report payload.

report.product_list[] items

Each element describes a product observed in the scan.

• brand (string)

• brand_id (int)

• category (string)

• category_id (int)

• manufacturer (string)

• manufacturer_id (int)

• product (string)

• product_id (int)

• upc (string)