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.
- Log in and open API & Webhooks in your account.
- Create an API key. It is shown once – store it in your server's secret store.
- 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.
- Scopes:
readallows GET requests,writealso allows creating, changing and deleting. - Who can create keys: the account owner and team admins. A key created by a team admin stops working when that person is no longer an admin of the team.
- Keep keys on the server. The API does not allow browser (CORS) requests.
- HTTPS only. Requests over plain HTTP are rejected with
403 https_required– if that happens, treat the key as exposed and replace it. - Revoked keys stop working immediately. Keys of a disabled account stop working as well.
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"
}
} | Status | Codes |
|---|---|
| 400 | invalid_json, invalid_parameter, invalid_cursor, invalid_format, invalid_size, invalid_days, invalid_idempotency_key |
| 401 | unauthorized – missing, invalid or revoked key, or disabled account |
| 403 | https_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) |
| 404 | not_found |
| 409 | static_content_immutable, idempotency_in_progress (retry shortly) |
| 413 / 415 | payload_too_large (more than 1 MB), unsupported_media_type (send application/json) |
| 422 | validation_failed (also for unknown fields), type_not_supported, folder_not_found, invalid_logo, not_scannable, url_blocked, subdomain_unavailable, idempotency_key_reused |
| 429 | rate_limited, monthly_limit_reached |
| 5xx | internal_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-codes | List (filters: folder_id, type, dynamic, status, search, limit, cursor) |
| POST | /qr-codes | Create |
| 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}/pause | Pause |
| POST | /qr-codes/{id}/activate | Activate (counts against the dynamic code quota) |
| GET | /types | Types 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
} - dynamic (default
true): the pattern encodes a short URL, so you can change the target later and get statistics. Static codes encode the content directly and can never change. Some types are only available as dynamic codes – seeGET /types. - password, expires_at, max_scans, custom_subdomain: dynamic codes only. Password protection and custom subdomains depend on the plan.
- design: same options as the editor (colors as
#RRGGBB, styles, frame, logo). Before saving we check that the code is still scannable with the chosen design; otherwise you getnot_scannable. - URLs are checked by the same security screening as in the web app. A suspicious URL is rejected (
url_blocked) or the code is created with statuspending_review. statusis one ofactive,paused,pending_revieworblocked(blocked by our security review – it cannot be changed or activated).- Strict input: unknown fields are rejected with
422, anddynamicmust be a JSON boolean (true/false, not a string). - Idempotency-Key (1–100 printable ASCII characters, case-sensitive): sending the same POST with the same key within 24 hours returns the first response (header
Idempotent-Replayed: true) instead of creating a second code. While the first request is still running, a retry gets409 idempotency_in_progress.
Update
Send only the fields you want to change. What is encoded in a printed pattern never changes:
- Dynamic codes:
contentreplaces all type fields (for example a new target URL).designis merged with the current design. - Static codes: only
title,folder_idanddesign. Changingcontentreturns409 static_content_immutable– create a new code instead. - Codes that are locked because the plan limit for dynamic codes is exceeded cannot be changed (
403 code_locked), just like in the web app. nullremovespassword,expires_at,max_scansor the folder.
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.
| Type | Fields |
|---|---|
| url | url* |
| text | text* |
email*, email_subject, email_message, email_cc, email_bcc | |
| phone | phone* |
| sms | sms_phone*, sms_message |
whatsapp_phone*, whatsapp_message | |
| vcard | vcard_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 |
| wifi | wifi_ssid*, wifi_password* (not for nopass), wifi_security (WPA, WPA2, WPA3, WEP, nopass), wifi_hidden |
| event | event_title*, event_start* (e.g. 2026-11-05T18:00), event_end, event_location, event_description |
| geolocation | latitude*, longitude* |
| app_store | app_name*, at least one of ios_available + ios_url, android_available + android_url, web_available + web_url |
| payment | payment_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_media | social_platform* (instagram, linkedin, tiktok, youtube, facebook, twitter, snapchat, custom), social_profile_input* (handle or profile URL), custom_url for custom |
| lost_found | lostfound_item_label*, lostfound_owner_email and/or lostfound_owner_phone*, lostfound_visibility (on_request, immediate), lostfound_reveal_mode (mediated, direct) |
| page | page_id* – number of a landing page of your account (shown in the page editor URL) |
| page_menu | page_id* – number of a menu page |
| survey | page_id* – number of a survey page |
| reviews | page_id* – number of a review page |
| loyalty | loyalty_program_id* – number of a loyalty program (shown in the URL of the loyalty page) |
| raffle | raffle_id* – number of a prize draw (shown in the URL of the prize draw page) |
| ticket_reg | ticket_event_id* – id of a ticket event from GET /v1/ticket-events (dynamic only; the scan opens the registration form) |
| ab_test | ab_variants* – list of {"kind": "url", "label": "A", "url": "https://…"} (2 or more), ab_split (equal or manual with share per variant) |
| google_review | google_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).
GET /ticket-events: all ticket events withtickets_issuedandtickets_used.GET /ticket-events/{event_id}: one event, including itscategories.GET /ticket-events/{event_id}/tickets: its tickets, filter with?status=valid, paginated like QR codes (limitup to 500,cursor).POST /ticket-events/{event_id}/ticketswith{"count": 50, "category_id": null}: creates up to 1000 tickets and returns them (201). The plan limits tickets per event (403 limit_reached); if support has locked tickets for the account, creating tickets gives403 account_locked; the capacity of the event or category gives409 capacity_reached. Send anIdempotency-Keyto retry safely.
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:
GET: the ticket withstatus:valid,used,used_today,not_today,void,not_yet,expiredorpaused.PATCHwithholder_name,holder_email,seat,language: guest details. Only the fields you send change.POST …/redeem: redeems one use, exactly like the staff gesture at the entrance (with entry days: once per day). If not possible:409 not_redeemablewithdetails.status. Triggers theticket.redeemedwebhook withredeemed_via: "api".POST …/undo-redeem: takes back the last redemption.POST …/voidandPOST …/restore: block or unblock a ticket.
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).
| Event | When |
|---|---|
| qr.scanned | A 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.created | A QR code was created (web app or API) |
| qr.updated | A QR code was changed, moved, paused or activated |
| qr.deleted | A QR code was deleted |
| form.submitted | A visitor sent a form on one of your pages |
| loyalty.stamp_added | Stamps were added to a loyalty card |
| loyalty.reward_redeemed | A reward was redeemed |
| review.submitted | A review was submitted on a review page |
| survey.submitted | A visitor completed a survey (answers by question ID, hidden fields, score) |
| ticket.redeemed | A ticket was validated (gesture on any device that opens the ticket, web app or API) |
| webhook.test | Test event (button "Send test" or POST /webhooks/{id}/test) |
Delivery
- We usually send an event right after it happens. Answer with a
2xxstatus within 5 seconds; do longer work afterwards. Only the first 2,000 bytes of your response are read. - If delivery fails, we retry after 15 min, 30 min, 1 h, 2 h, 6 h, 12 h and 24 h – up to 8 attempts in total. While your endpoint is failing, new events for it wait for the next retry run (every 15 minutes) instead of being sent immediately.
- If your endpoint has only returned errors for 3 days (and at least 30 failed attempts), we disable the webhook and notify the account owner by email.
- While a webhook is paused or disabled, no new events are created for it. Events that were already waiting are sent after you enable it again, if they are not older than 7 days.
- Events can arrive more than once and not always in order. Use the event
idto ignore duplicates. - Requirements for the URL:
https, port 443, a public address with an IPv4 record. Redirects are not followed. - Deliveries are kept for 30 days. You can resend a single delivery, or all failed deliveries
of the last days at once (account page or
POST /webhooks/{id}/resend-failedwith{"days": 7}).
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.