Black Friday-Weeks 50% Rabatt auf alle bezahlten Pläne · gültig bis 30.11.2026 Preise ansehen →
Logo

Developers

QRown API & Webhooks

Create and manage QR codes from your own systems, download print-ready images, read scan statistics – and receive scans, form entries, loyalty stamps and reviews automatically.

1. Getting started

Base URL: https://qrown.io/api/v1. Requests and responses use JSON (UTF-8). Successful responses wrap the result in data; lists add next_cursor.

  1. Log in and open API & Webhooks in your account.
  2. Create an API key. It is shown once – store it in your server's secret store.
  3. Send your first request:
curl https://qrown.io/api/v1/qr-codes \
  -H "Authorization: Bearer qrn_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "url", "title": "Menu", "content": {"url": "https://example.com/menu"}}'

The response contains the new code including short_url (what the pattern encodes) and image_url. A dynamic code keeps its pattern forever – you can change the target at any time.

2. Authentication

Send the key in the Authorization header: Authorization: Bearer qrn_live_…. A key belongs to one account and gives access to all its QR codes, folders, statistics, webhooks and tickets.

3. Limits

Each account has a monthly request limit and a per-second limit, depending on the plan. Authenticated responses report the monthly status in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time) whenever the plan has a monthly limit. When a limit is reached, the API answers with 429 and a Retry-After header.

Plan Requests / month Requests / second Webhooks Scan events / month
Standard 10,000 5 3 10,000
Premium 50,000 10 10 50,000
Expert 250,000 25 25 250,000

Creating dynamic codes also counts against the dynamic code quota of the plan, exactly like in the web app. GET /account returns the current usage.

4. Errors

{
  "error": {
    "code": "validation_failed",
    "message": "content.url is missing"
  }
}
StatusCodes
400invalid_json, invalid_parameter, invalid_cursor, invalid_format, invalid_size, invalid_days, invalid_idempotency_key
401unauthorized – missing, invalid or revoked key, or disabled account
403https_required, plan_required, insufficient_scope, type_not_in_plan, feature_not_in_plan, quota_exceeded, limit_reached, code_locked (plan limit exceeded – upgrade or delete other codes), code_blocked (blocked by the security review), disabled_by_support, account_locked (tickets locked by support)
404not_found
409static_content_immutable, idempotency_in_progress (retry shortly)
413 / 415payload_too_large (more than 1 MB), unsupported_media_type (send application/json)
422validation_failed (also for unknown fields), type_not_supported, folder_not_found, invalid_logo, not_scannable, url_blocked, subdomain_unavailable, idempotency_key_reused
429rate_limited, monthly_limit_reached
5xxinternal_error, render_failed, unavailable – retry later

Every response has an X-Request-Id header. Please include it when you contact support.

5. QR codes

GET/qr-codesList (filters: folder_id, type, dynamic, status, search, limit, cursor)
POST/qr-codesCreate
GET/qr-codes/{id}Get one
PATCH/qr-codes/{id}Update
DELETE/qr-codes/{id}Delete (the short code is retired, never reused)
POST/qr-codes/{id}/pausePause
POST/qr-codes/{id}/activateActivate (counts against the dynamic code quota)
GET/typesTypes available in your plan, static and dynamic

Create

POST /api/v1/qr-codes
Idempotency-Key: 6f1c2d9e-order-4711

{
  "type": "url",
  "title": "Summer menu",
  "dynamic": true,
  "content": { "url": "https://example.com/menu" },
  "utm": { "utm_source": "poster", "utm_campaign": "summer" },
  "design": {
    "foreground_color": "#0F3D2E",
    "pattern_style": "rounded",
    "frame_style": "none"
  },
  "folder_id": 12,
  "expires_at": "2026-12-31T23:59:00+01:00",
  "max_scans": 5000
}

Update

Send only the fields you want to change. What is encoded in a printed pattern never changes:

PATCH /api/v1/qr-codes/k7fp2ab
{ "content": { "url": "https://example.com/autumn-menu" } }

Pagination

Lists return up to limit items (max. 100), newest first. If there are more, pass next_cursor as cursor to get the next page.

6. Content fields per type

The content object uses the same fields as the web editor. Required fields are marked with *. Phone numbers in international format (+41791234567). Not yet available via the API: file uploads and smart-redirect rules.

TypeFields
urlurl*
texttext*
emailemail*, email_subject, email_message, email_cc, email_bcc
phonephone*
smssms_phone*, sms_message
whatsappwhatsapp_phone*, whatsapp_message
vcardvcard_firstname or vcard_lastname*, vcard_organization, vcard_title, vcard_email, vcard_phone, vcard_mobile, vcard_website, vcard_street, vcard_city, vcard_postal_code, vcard_country, vcard_linkedin, vcard_xing, vcard_instagram, vcard_facebook, vcard_youtube
wifiwifi_ssid*, wifi_password* (not for nopass), wifi_security (WPA, WPA2, WPA3, WEP, nopass), wifi_hidden
eventevent_title*, event_start* (e.g. 2026-11-05T18:00), event_end, event_location, event_description
geolocationlatitude*, longitude*
app_storeapp_name*, at least one of ios_available + ios_url, android_available + android_url, web_available + web_url
paymentpayment_method* (paypal, stripe, twint, bitcoin, bank_transfer) and its fields: paypal_username, paypal_amount, paypal_currency · stripe_url · twint_url · bitcoin_address, bitcoin_amount, bitcoin_label · bank_iban, bank_recipient, bank_bic, bank_amount, bank_currency, bank_reference
social_mediasocial_platform* (instagram, linkedin, tiktok, youtube, facebook, twitter, snapchat, custom), social_profile_input* (handle or profile URL), custom_url for custom
lost_foundlostfound_item_label*, lostfound_owner_email and/or lostfound_owner_phone*, lostfound_visibility (on_request, immediate), lostfound_reveal_mode (mediated, direct)
pagepage_id* – number of a landing page of your account (shown in the page editor URL)
page_menupage_id* – number of a menu page
surveypage_id* – number of a survey page
reviewspage_id* – number of a review page
loyaltyloyalty_program_id* – number of a loyalty program (shown in the URL of the loyalty page)
raffleraffle_id* – number of a prize draw (shown in the URL of the prize draw page)
ticket_regticket_event_id* – id of a ticket event from GET /v1/ticket-events (dynamic only; the scan opens the registration form)
ab_testab_variants* – list of {"kind": "url", "label": "A", "url": "https://…"} (2 or more), ab_split (equal or manual with share per variant)
google_reviewgoogle_place_id or google_review_url_manual*

7. Images and statistics

GET /qr-codes/{id}/image?format=svg|png|pdf&size=1000 returns the image with the saved design (size 100–4000). The image is always rendered from the saved content – it matches previous downloads exactly.

GET /qr-codes/{id}/stats?days=30 returns scans, unique visitors, scans per day, devices and the top 10 countries. The period is limited by the statistics history of your plan.

{
  "data": {
    "days": 30,
    "scans": 1284,
    "unique_visitors": 917,
    "by_day": [{ "date": "2026-10-09", "scans": 54 }],
    "by_device": { "mobile": 1130, "desktop": 121, "tablet": 33 },
    "by_country": { "CH": 1012, "DE": 188 }
  }
}

8. Folders

GET /folders lists folders with their number of codes. POST /folders with {"name": "Events", "parent_id": null, "color": "#3B82F6"} creates one. Use the folder id as folder_id for QR codes.

9. Tickets

Ticket events (concerts, courses, 10-visit cards …) are set up in the dashboard under Tickets; the API reads them and creates, looks up and redeems their tickets. Requires the tickets feature in the plan of the account (otherwise 403 plan_required).

A single ticket is addressed either by its number within the event, /ticket-events/{event_id}/tickets/ABCD-EF23, or by its token, /tickets/{token}. The token is the t= value in the link that the ticket QR code contains, so a scanner app can use it directly. Both paths support the same operations:

POST /api/v1/tickets/3f0c9a1b2d4e5f60718293a4b5c6d7e8/redeem

200 OK
{
  "data": {
    "redeemed": true,
    "number": "ABCD-EF23",
    "status": "used",
    "uses": 1,
    "uses_allowed": 1,
    "used_days": null,
    "voided": false,
    "category": { "id": 3, "name": "VIP" },
    "holder": { "name": "Anna Muster", "email": "anna@example.com" },
    "seat": "Row 4, seat 12",
    "language": "de",
    "mailed_at": "2026-10-08T09:12:00+02:00",
    "token": "3f0c9a1b2d4e5f60718293a4b5c6d7e8",
    "url": "https://qrown.io/ticket.php?t=3f0c9a1b2d4e5f60718293a4b5c6d7e8",
    "image": { "png": "https://qrown.io/ticket-qr.php?t=3f0c…&format=png", "svg": "https://qrown.io/ticket-qr.php?t=3f0c…&format=svg" },
    "last_used_at": "2026-10-09T19:42:00+02:00",
    "created_at": "2026-10-01T10:00:00+02:00"
  }
}

The token opens the ticket: treat it like a password and do not publish ticket lists.

10. Webhooks

A webhook sends an HTTPS POST with a JSON body to your URL whenever an event happens. Add webhooks on the API & Webhooks page or via the API (/webhooks, /webhooks/{id}/test, /webhooks/{id}/rotate-secret, /webhooks/{id}/deliveries, /webhooks/{id}/resend-failed).

EventWhen
qr.scannedA dynamic code was scanned (bots and repeated scans by the same visitor within an hour are not counted). Limited per month depending on the plan.
qr.createdA QR code was created (web app or API)
qr.updatedA QR code was changed, moved, paused or activated
qr.deletedA QR code was deleted
form.submittedA visitor sent a form on one of your pages
loyalty.stamp_addedStamps were added to a loyalty card
loyalty.reward_redeemedA reward was redeemed
review.submittedA review was submitted on a review page
survey.submittedA visitor completed a survey (answers by question ID, hidden fields, score)
ticket.redeemedA ticket was validated (gesture on any device that opens the ticket, web app or API)
webhook.testTest event (button "Send test" or POST /webhooks/{id}/test)

Delivery

Headers of every delivery:

Content-Type: application/json
User-Agent: QRown-Webhooks/1.0 (+https://qrown.io/developers.php)
QRown-Event: qr.scanned
QRown-Event-Id: evt_3f9a1c0e8b7d6a5f4e3d2c1b
QRown-Delivery: 81723
QRown-Signature: t=1791561600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

11. Verifying signatures

Each webhook has a secret (whsec_…). v1 is the hex HMAC-SHA256 of t + "." + raw body with that secret. Compare it in constant time and reject messages whose t is older than 5 minutes. Always use the raw request body, not re-encoded JSON.

Rotating the secret: for 24 hours after a rotation the header contains two signatures, one with the new and one with the previous secret (t=…,v1=…,v1=…). Accept the message if any v1 matches – the examples below do that – so you can switch to the new secret without missing events.

PHP

function qrownVerify(string $body, string $header, string $secret, int $tolerance = 300): bool
{
    $t = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($key === 't') $t = $value;
        if ($key === 'v1') $signatures[] = $value;
    }
    if ($t === null || !ctype_digit($t) || !$signatures || abs(time() - (int)$t) > $tolerance) return false;
    $expected = hash_hmac('sha256', $t . '.' . $body, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) return true;
    }
    return false;
}

$body = file_get_contents('php://input');
if (!qrownVerify($body, $_SERVER['HTTP_QROWN_SIGNATURE'] ?? '', getenv('QROWN_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);

Node.js

const crypto = require('crypto');

function qrownVerify(rawBody, header, secret, tolerance = 300) {
  const parts = (header || '').split(',').map(s => s.trim().split('='));
  const t = (parts.find(([k]) => k === 't') || [])[1];
  const signatures = parts.filter(([k]) => k === 'v1').map(([, v]) => v || '');
  if (!/^\d+$/.test(t || '') || !signatures.length || Math.abs(Date.now() / 1000 - Number(t)) > tolerance) return false;
  const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'));
  return signatures.some(s => {
    const b = Buffer.from(s);
    return b.length === expected.length && crypto.timingSafeEqual(expected, b);
  });
}

// Express: app.post('/qrown', express.raw({ type: 'application/json' }), (req, res) => { ... req.body.toString() ... })

Python

import hashlib, hmac, time

def qrown_verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = [part.strip().split("=", 1) for part in header.split(",") if "=" in part]
    t = next((v for k, v in parts if k == "t"), "")
    signatures = [v for k, v in parts if k == "v1"]
    if not t.isdigit() or not signatures or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in signatures)

12. Event payloads

All events share the same envelope:

{
  "id": "evt_3f9a1c0e8b7d6a5f4e3d2c1b",
  "type": "qr.scanned",
  "created_at": "2026-10-09T12:00:00Z",
  "data": { ... }
}

qr.scanned

No IP address, user agent or exact location is sent.

"data": {
  "qr_code": { "id": "k7fp2ab", "title": "Summer menu", "short_code": "k7Fp2" },
  "device": "mobile",
  "browser": "Safari",
  "country": "CH",
  "city": "Zurich",
  "ab_variant": null,
  "smart_rule": null,
  "scanned_at": "2026-10-09T12:00:00Z"
}

qr.created / qr.updated / qr.deleted

data.qr_code is the same object as in the API (GET /qr-codes/{id}). For qr.deleted only id and title.

form.submitted

"data": {
  "entry_id": 5521,
  "qr_code_id": "k7fp2ab",
  "page": { "id": 31, "title": "Table reservation" },
  "language": "de",
  "fields": [
    { "id": "f1", "label": "Name", "type": "text", "value": "Anna Muster" },
    { "id": "f2", "label": "E-mail", "type": "email", "value": "anna@example.com" }
  ],
  "submitted_at": "2026-10-09T12:00:00Z"
}

loyalty.stamp_added / loyalty.reward_redeemed

The guest's email address is never sent.

"data": {
  "program": { "id": 4, "name": "Café Sonnenschein" },
  "card": { "number": "48217731", "stamps": 7, "stamps_required": 10, "rewards_redeemed": 1 },
  "stamps_added": 1,
  "staff": "Counter",
  "occurred_at": "2026-10-09T12:00:00Z"
}

For loyalty.reward_redeemed, stamps_used replaces stamps_added.

review.submitted

contact is only included if the guest agreed to be contacted.

"data": {
  "response_id": 902,
  "qr_code_id": "m3xk9qa",
  "score": 80,
  "is_low": false,
  "answers": [{ "id": "q1", "question": "How was your visit?", "type": "stars", "value": 4 }],
  "comment": "Great coffee",
  "contact": null,
  "language": "de",
  "submitted_at": "2026-10-09T12:00:00Z"
}

ticket.redeemed

Tickets are anonymous; no personal data is sent. redeemed_via: gesture, admin or api. day is the entry day for tickets with fixed entry days, otherwise null.

"data": {
  "ticket": { "number": "ABCD-EF23", "uses": 1, "uses_allowed": 1 },
  "event": { "id": "hK3mP9qRtW", "title": "Autumn concert 2026" },
  "day": "2026-10-09",
  "redeemed_via": "gesture",
  "redeemed_at": "2026-10-09T19:42:00Z"
}

13. Versioning

This is version 1 (/api/v1). Within v1 we only add things: new endpoints, new optional fields, new event types. Your integration should ignore unknown fields. Breaking changes will come as a new version.

Questions? Contact support.