BestQRs Documentation

Understanding how QR codes actually work — and why dynamic codes are the only serious choice for any printed campaign.

Static vs. Dynamic QR Codes

A QR code is a machine-readable encoding of a text string. The critical difference between static and dynamic codes is where that string points.

The Interceptor Architecture

When you create a QR code on BestQRs, we encode a short tracking URL — never your final destination. Every scan hits our Interceptor, which evaluates your Smart Rules in real-time using Redis, then performs a near-instant redirect. Your printed code stays valid forever, even as destinations change.

A well-branded QR code builds trust before the user even scans it — and dramatically improves scan rates. Here's how to get the design right.

Pattern Styles

BestQRs supports four module-drawing styles. All are equally scannable when contrast is sufficient — choose the one that fits your brand.

Contrast Safety

A QR scanner works by detecting the difference in light reflected between dark modules and a light background. Too little contrast and phones fail to scan — especially in bright sunlight or on budget cameras. BestQRs enforces a real-time contrast check using the WCAG luminance formula.

Center Logos & CTA Frames

Two branding tools that boost both visual recognition and scan rates. Used together, they can increase conversions by over 80% compared to a plain, unbranded code.

The most powerful feature on BestQRs. One printed QR code — infinite possible destinations, automatically routed by device, day, and time of day.

Mixed Rule Logic

Each QR code can have multiple ordered rules. When a scan arrives, BestQRs evaluates rules from top to bottom using strict AND logic: a rule fires only when every one of its set conditions is satisfied simultaneously. This is called "fail-fast" — if a single condition fails, BestQRs skips immediately to the next rule.

User-Agent Cheat Sheet

The UA field is matched as a case-insensitive substring of the browser's full User-Agent string. You don't need the full string — just a unique identifying word. Here are the proven values:

Days of Week & Time Ranges

Rules can be restricted to specific days of the week and a time window. All evaluation happens in the timezone set in your Account Settings — not the scanner's timezone. Set this correctly before configuring time-based rules.

Real-World Use Cases

A QR code can encode much more than a web link. BestQRs can also host files for you, generate contact cards, and produce static codes for Wi-Fi, SMS, email, and WhatsApp — all from the same designer.

📎 Hosted File QRs

Upload a PDF, image, audio file, or any document and BestQRs will host it for you at a short URL. The QR points to /f/<slug>/ — when scanned, the file is served directly with browser caching, edge delivery, and no extra hop. Replace the file at any time without changing the QR code.

📇 vCard & Digital Business Cards

Two distinct ways to put your contact details behind a QR code, depending on whether you want a raw download or a polished landing page.

📶 Wi-Fi, SMS, Email & WhatsApp QRs

Four more static payload types — each encodes a structured action that the phone recognises and offers to perform automatically.

Tools for generating, managing, and integrating large numbers of QR codes — built for teams running real campaigns.

📤 Bulk Upload

Upload a CSV and BestQRs will create one Link per row, generate the branded QR images, and stream the lot back as a downloadable ZIP. Ideal when you need to seed dozens or hundreds of codes at once — product packaging, name tags, asset tracking.

🎯 Campaigns

A Campaign is a named group of Links you manage as one unit. Pause or resume the entire batch with a single click, schedule them to auto-deactivate on a date, or download the whole set as a ZIP. Perfect for time-bound promotions, conference batches, or seasonal pushes.

📧 Scheduled Reports

Get a recurring email digest of scan activity across your dynamic QR codes instead of checking the dashboard manually. Create as many reports as you need from the Reports page, each with its own name, cadence, and recipients.

👥 Teams & Invites

Every account has an Organization. Invite teammates by email and they'll get a link to create their account and join. Members share Links, Campaigns, and storage — but only Admins can change billing, invite or remove members, and manage API keys.

🔔 Scan Webhooks

Set a Webhook URL on your Organization and BestQRs will POST a JSON payload to it after every scan, once geo and device data have been resolved. Drop scans straight into your CRM, marketing automation, or Slack channel.

POST https://your-server.example/qr-events
Content-Type: application/json

{
  "event":         "qr.scan",
  "link_slug":     "abc12345",
  "label":         "Spring Flyer",
  "target_url":    "https://example.com/spring",
  "timestamp":     "2025-04-12T14:32:01Z",
  "country":       "GB",
  "city":          "London",
  "device_type":   "iphone",
  "campaign_source": "qr"
}

Webhook delivery uses exponential backoff (5 retries, 10 s → 5 min) so transient outages on your side won't drop events. A request is considered delivered on any 2xx response.