Scan Events

The Scan Events API provides access to consumer interaction records when the Digital Links of supply chain objects (products, containers, assets etc.) are loaded in a browser - usually when scanned via mobile phone.

Overview

Scan events capture detailed information about consumer interactions with TrackVision-enabled products and assets, including:

• Scan Analytics - When, where, and how products are scanned
• Consumer Insights - Device, location, and demographic data
• Engagement Tracking - Link types accessed and user behavior
• Performance Metrics - Response times and success rates

The scan_event Object

Field Name	Type	Description
id	uuid	Primary key of the scan event.
user_created	object	User who created the record. Read-only.
date_created	datetime	When the scan event record was created. Read-only.
user_updated	object	User who last updated the record. Read-only.
date_updated	datetime	When the scan event record was last updated. Read-only.
scan_date	datetime	When the actual scan occurred.
device	string	Device information (manufacturer, model).
region	string	Geographic region where the scan occurred.
operating_system	string	Operating system of the scanning device.
browser	string	Browser used for the scan.
browser_version	string	Version of the browser.
device_type	string	Type of device (mobile, tablet, desktop).
city	string	City where the scan occurred.
country	string	Country where the scan occurred.
timezone	string	Timezone of the scan location.
link_type	string	Type of Digital Link accessed (pip, traceability, etc.).
event_type	string	Type of scan event (qr_scan, digital_link, etc.).
gps_latitude	number	GPS latitude if available from device.
gps_longitude	number	GPS longitude if available from device.
ip_latitude	number	Latitude derived from IP address.
ip_longitude	number	Longitude derived from IP address.
http_request_header	object	Complete HTTP request headers.
http_request_body	object	HTTP request body if applicable.
decoded_ip_info	object	Decoded IP geolocation information.
decoded_user_agent	object	Parsed user agent information.
source_code_url	string	Original scanned URL or code data.
resolved_to_url	string	Final resolved URL after redirections.
response_data	object	Response data sent to the consumer.
response_code	integer	HTTP response code returned.
map	object	Additional mapping or context data.
product	object	Product associated with the scan.
account	object	Account that owns the scanned product. (Multi-tenant installations only)
offer_channel	object	Marketing offer channel if applicable.
prospect	object	Prospect if part of a marketing campaign.
gtin	string	Global Trade Item Number from the scan.
serial	string	Serial number if present in the scan.
lot	string	Lot number if present in the scan.
sscc	string	Serial Shipping Container Code if applicable.
gln	string	Global Location Number if applicable.
gln_extension	string	GLN extension if present.
pgln	string	Party GLN if applicable.
grai	string	Global Returnable Asset Identifier if applicable.
giai	string	Global Individual Asset Identifier if applicable.
short_code	string	Short URL or code used for the scan.
query_parameters	string	URL query parameters from the scan.
client_id	string	Client identifier associated with the scan.
execution_logs	object	Detailed execution logs and processing information.

Retrieval Endpoints

Get All Scan Events

Retrieve scan events with filtering and pagination:

GET https://yourbrand.trackvision.ai/items/scan_event
Authorization: Bearer your-token

Query Parameters

Supports all global query parameters.

Example Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "scan_date": "2024-01-15T14:30:00Z",
      "gtin": "00614141999996",
      "serial": "12345",
      "link_type": "pip",
      "event_type": "qr_scan",
      "device_type": "mobile",
      "operating_system": "iOS",
      "browser": "Safari",
      "country": "US",
      "city": "Boston",
      "region": "Massachusetts",
      "gps_latitude": 42.3601,
      "gps_longitude": -71.0589,
      "response_code": 200,
      "source_code_url": "https://customer.tvai.me/01/00614141999996/21/12345",
      "resolved_to_url": "https://customer.tvai.me/01/00614141999996/21/12345?linkType=pip"
    }
  ]
}

Get Single Scan Event

Retrieve a specific scan event by ID:

GET https://yourbrand.trackvision.ai/items/scan_event/{id}
Authorization: Bearer your-token

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "scan_date": "2024-01-15T14:30:00Z",
  "date_created": "2024-01-15T14:30:01Z",
  "gtin": "00614141999996",
  "serial": "12345",
  "link_type": "pip",
  "event_type": "qr_scan",
  "device": "iPhone 15 Pro",
  "device_type": "mobile",
  "operating_system": "iOS 17.1",
  "browser": "Safari",
  "browser_version": "17.1",
  "country": "US",
  "city": "Boston",
  "region": "Massachusetts",
  "timezone": "America/New_York",
  "gps_latitude": 42.3601,
  "gps_longitude": -71.0589,
  "ip_latitude": 42.3584,
  "ip_longitude": -71.0598,
  "response_code": 200,
  "source_code_url": "https://customer.tvai.me/01/00614141999996/21/12345",
  "resolved_to_url": "https://customer.tvai.me/01/00614141999996/21/12345?linkType=pip",
  "decoded_user_agent": {
    "browser": "Safari",
    "version": "17.1",
    "os": "iOS",
    "os_version": "17.1",
    "device": "iPhone",
    "device_model": "iPhone 15 Pro"
  },
  "decoded_ip_info": {
    "country": "US",
    "region": "MA",
    "city": "Boston",
    "timezone": "America/New_York",
    "isp": "Verizon Wireless"
  }
}

Use Cases

Consumer Engagement Analysis

• Track which products generate the most consumer interest
• Understand peak scanning times and patterns
• Identify popular link types and content

Geographic Market Intelligence

• Analyze product performance by region
• Identify expansion opportunities
• Track cross-border product movement

Anti-counterfeiting

• Monitor unusual scanning patterns
• Detect potential counterfeit products
• Verify authentic product distribution

Marketing Campaign Effectiveness

• Measure QR code campaign performance
• Track consumer journey through Digital Links
• Optimize content based on device and location data