Skip to main content
A QR Code is a permanent short URL of the form https://award.ee/<slug> paired with a programmable destination, a status, and an immutable scan history. Print the code once, change where it sends visitors any time.

​
The scan flow

Two things matter for integrations:
  1. Destination at scan time, not print time. The row stored on the scan captures the destination as it was at the moment of resolution. Change the destination tomorrow and tomorrow’s scans go somewhere else — yesterday’s history stays accurate.
  2. URL params merge. Static params from qr_codes/{id}/url-params (and any inherited from the QR group) get appended to the redirect. Live query string params from the visitor override on key collision.

​
The id parameter accepts slugs too

Every endpoint that takes {id} accepts either the UUID or the public_slug. Useful when you only know the short slug from a scan URL: 
# By UUID
curl https://api.awardee.dev/v1/qr-codes/8f3a9d2e-1b4c-4f5d-9e8a-7c3b2a1d0f9e \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

# By public_slug
curl https://api.awardee.dev/v1/qr-codes/abc1234 \
  -H "Authorization: Bearer aw_live_4f8a3c7e2d1b9a5c6f8e3d2c1b4a9f7e"

​
Status lifecycle

StatusMeaning
unconfiguredNo destination set. Scans show a “not configured” screen.
activeLive. Scans resolve and redirect.
inactivePaused. Row stays, scans show a “paused” screen. Useful for recall, seasonal pulls, A/B holds.
archivedSoft-deleted. Hidden from list views. Historical scans still readable.

​
Sub-resources

Properties

Operator-defined K/V metadata on the code. Used for internal labels — venue, batch, ad campaign, etc. Replaced as a set via PUT.

URL params

Static query params merged into the redirect URL. Common use: utm_source, utm_medium, ref. Live visitor params override on key collision.

Scans

Immutable scan history. Cursor-paginated. Each row captures the destination at scan time, the visitor’s user agent, coarse geo (country / region / city), and the merged query params.

​
URL param merge example

A QR code has static params utm_source=poster&utm_campaign=fall24. The visitor scans https://award.ee/abc1234?utm_source=email. The merged params on the redirect become: 
?utm_source=email&utm_campaign=fall24
Live wins on utm_source; the static utm_campaign survives.

​
Webhook events

EventFires on
qr_code.updatedPATCH /qr-codes/{id} or any dashboard edit.
qr_code.scannedA visitor scanned the short URL and was successfully redirected.
Subscribe and verify signatures per the webhooks guide.