API Reference

Scans & Analytics

Every time a QPR Code is scanned, 3QPR records a scan event. The analytics endpoints give you real-time and aggregated data on scan volume, geography, and conversation engagement — perfect for dashboards and campaign measurement.

GET/v1/scans

List scans

Returns a paginated list of scan events across all your QPR Codes or scoped to a specific code.

Query parameters

Param	Default	Description
qpr_code_id	—	Filter to a specific QPR Code ID
limit	50	Max items to return (1–200)
offset	0	Pagination offset
since	—	ISO-8601 timestamp — return scans after this time
until	—	ISO-8601 timestamp — return scans before this time

curl "https://api.3qpr.com/v1/scans?qpr_code_id=qpr_01HXYZ789ABC&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200json

{
  "scans": [
    {
      "id": "scan_01HABC",
      "qpr_code_id": "qpr_01HXYZ789ABC",
      "short_id": "hc9m3r",
      "scanned_at": "2026-03-20T15:30:00Z",
      "country": "US",
      "region": "CA",
      "city": "San Francisco",
      "device": "mobile",
      "conversation_started": true,
      "conversation_messages": 6,
      "metadata": {}
    }
  ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

GET/v1/qpr-codes/:id/analytics

Get code analytics

Returns aggregated analytics for a single QPR Code — total scans, unique devices, conversation rate, and a daily time series.

Query parameters

Param	Default	Description
period	30d	Time window: 7d \| 30d \| 90d \| all
granularity	day	Bucketing for timeseries: hour \| day \| week

curl "https://api.3qpr.com/v1/qpr-codes/qpr_01HXYZ789ABC/analytics?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200json

{
  "qpr_code_id": "qpr_01HXYZ789ABC",
  "period": "30d",
  "scans_total": 142,
  "scans_unique_devices": 138,
  "conversation_rate": 0.74,
  "avg_messages_per_conversation": 5.2,
  "top_countries": [
    { "country": "US", "scans": 89 },
    { "country": "GB", "scans": 21 },
    { "country": "CA", "scans": 14 }
  ],
  "timeseries": [
    { "date": "2026-03-01", "scans": 8, "conversations": 6 },
    { "date": "2026-03-02", "scans": 5, "conversations": 4 }
  ]
}

Scan object

Field	Type	Description
id	string	Unique scan ID
qpr_code_id	string	Parent QPR Code ID
scanned_at	string	ISO-8601 timestamp of the scan event
country	string	ISO-3166 alpha-2 country code (may be null)
region	string	Region / state code (may be null)
city	string	City name (may be null)
device	string	mobile \| tablet \| desktop \| unknown
conversation_started	boolean	Whether the user opened a conversation
conversation_messages	number	Total messages exchanged (0 if no conversation)
metadata	object	Pass-through metadata from the QPR Code

Tip: For real-time scan processing, subscribe to the scan.created webhook event instead of polling this endpoint. See Webhooks for details.