Public scan tracking

Overview

Public, unauthenticated endpoint hit when an end customer scans a QR code. Resolves the unique_code to a QrCode (falling back to a QrCodeTemplate, then its parent QrCode) and records a scan-history row (IP, user-agent, referer, optional geo/device fields). Then bumps last_scanned_at, and returns the destination URL.

Prerequisites

• No authentication — this endpoint is public.

Base URL

Endpoint

POST /api/v1/qr-codes/{unique_code}/scan

Authentication

• No bearer token required.

• No authentication required.

• Registered outside the authenticated group, rate-limited to 30 requests per minute per IP.

• Anyone with the code may call it.

Rate limit

• 30 requests/min.

Request body

• Path: unique_code (string, required) — unique code of a QR code or QR template.
• Body (untyped Request, all optional; The endpoint stores only included fields):

{
  "latitude": 40.7128,
  "longitude": -74.006,
  "device_type": "mobile",
  "browser": "Chrome",
  "os": "iOS",
  "metadata": {
    "campaign": "summer"
  }
}

Response

• data.data.destination_url (string) — resolved via getDestinationUrl.
• data.data.qr_code_name (string)
• data.data.scan_count (int) — total scan-history rows for the QR code.
• data.data.last_scanned_at (datetime, nullable)
• data.message (string) — "QR code scanned successfully".

200 Success · 200

{
  "data": {
    "data": {
      "destination_url": "https://example.com/lp/1?store_id=8748",
      "qr_code_name": "Lobby",
      "scan_count": 10,
      "last_scanned_at": "2026-06-26T10:30:00.000000Z"
    },
    "message": "QR code scanned successfully"
  }
}

Errors

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/qr-codes/<unique-code>/scan" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"latitude": 40.7128, "longitude": -74.006, "device_type": "mobile", "browser": "Chrome", "os": "iOS", "metadata": {"campaign": "summer"}}'