QR code API documentation

The QR code API makes QR codes and manages dynamic QR codes over HTTPS. Each endpoint below says which of three levels of access it needs.

To try a request first, the QR code API page builds one and shows the reply from a sample workspace.

No account. GET /api/qr/free returns a QR code as an SVG or a PNG, with no key and nothing to sign up for.

POST /api/qr/decode goes the other way: post an image and it reads the code out. It takes no key either.

A Free key. Create a key on any plan in Dashboard → API and it renders: GET /api/qr with every format, colour, shape and size, and GET /api/barcode.

A key on a plan without API access carries the render scope alone, so it can't read or change your account.

Starter and above. The account: create dynamic codes and short links, re-point what is already printed, smart routing, folders, tags, custom domains, scans and analytics, QR Menus and QR Forms. Webhooks come with Business.

Render (GET /api/qr) returns a static QR code image (SVG, PNG, JPG, WebP or PDF) for a link, Wi-Fi network, contact card, email, phone number, SMS, text or product. Nothing is stored; the same request always returns the same file.

Create (POST /api/v1/codes) saves a code to your account. A dynamic code gets a short link, so you can change where it points after it is printed, and it counts its scans.

Shorten (POST /api/v1/links) makes a short link on its own, with no QR code. It is the same kind of link a dynamic code has: you can edit it, route it and count its clicks.

Use it where you paste a link rather than print a code. You can ask for its QR code later.

Organise codes the way the dashboard does: your own custom domains and custom links, folders, tags, campaign tags and bulk actions.

Read scans for one code or the whole workspace, your QR Menus, your QR Forms and their answers, and hear about each scan and answer as it happens with webhooks.

The base URL is https://app.qrsalt.com. Requests and responses are JSON, except images.

Send your API key as a bearer token. Every plan can create one in Dashboard → API, including Free. A key is shown once, and only a hash is stored.

Two things decide what a key can do: its scopes, and what your plan includes. On Free, a key carries render: it makes images and reads nothing.

Everything about the account (codes, links, scans, webhooks) comes with Starter and above. Until then those calls answer 402 with the name of the plan you need.

Call the API from a server or a no-code tool, such as the connectors for n8n and Make, never from a web page.

Anyone can copy a key that sits in a web page, so the API sends no CORS headers. A missing or wrong key is a 401.

An app that people connect to their own workspace can sign in with QRSalt instead, and nobody has to paste a key.

GET /api/qr/free takes no key at all, and GET /api/v1/me works with any key, so a tool can tell whether the key is wrong or the plan does not include what it asked for.

A key can do only what you ticked when you made it. A script that prints labels needs to render, but it does not need to delete codes. Give each key only what its job needs, so a script run by mistake can’t delete anything.

A refusal names the missing scope. A 403 always means the key lacks a scope, so make a new key with that box ticked. A 402 means your plan does not include the feature.

Keys made before scopes existed have all four and keep working exactly as they did. On Starter and above you choose a key’s scopes when you make it; on lower plans every key is render only.

• render - Static QR codes and barcodes as images. Nothing is stored or read.
• read - List codes, links, folders, tags, QR Menus, QR Forms and their answers, and read scans.
• write - Create and change codes, links, folders, domains and webhook endpoints.
• delete - Delete codes, links, domains and webhook endpoints. A deleted code cannot be restored.

An app can connect to somebody’s workspace without a key: it signs them in with QRSalt, using OAuth 2.1 with PKCE.

This is how the Claude app and other MCP clients connect to the QR code MCP server, and your own integration can do the same.

Discovery. Every 401 from /api/v1 and /api/mcp has a WWW-Authenticate header with resource_metadata: the address of that endpoint’s metadata (RFC 9728), for example https://app.qrsalt.com/.well-known/oauth-protected-resource/api/v1.

It names the authorization server, whose own metadata is at https://app.qrsalt.com/.well-known/oauth-authorization-server (RFC 8414).

Your client. Register it with POST /oauth/register (RFC 7591), or use the https address of your client metadata document as the client_id. Every client is public: there is no client secret, and PKCE with S256 is required.

Redirect URIs must use https, or http on 127.0.0.1, [::1] or localhost, and must match exactly. A loopback redirect may use any port.

The one other address accepted is Cursor’s desktop callback, cursor://anysphere.cursor-mcp/oauth/callback, exactly as written.

Consent. Send the person to /oauth/authorize with response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256, scope and resource, which is https://app.qrsalt.com/api/v1 or https://app.qrsalt.com/api/mcp.

They sign in, choose a workspace where they are an owner or an admin, and tick the scopes. delete is never ticked for them, and the plan limits the rest as it does for a key.

The redirect back carries code, state and iss.

Tokens. Exchange the code at POST /oauth/token within 60 seconds, with the code_verifier. The access token lasts an hour and works only on the resource it was issued for.

The refresh token lasts 90 days and is replaced each time you use it. Using a replaced one again revokes the connection.

POST /oauth/revoke ends a connection, and so does Revoke under Dashboard → API → Connected apps.

A token acts as the person who approved it, with the same scopes, plan limits and rate limits as a key. It stops working if they leave the workspace or stop being an owner or admin.

A token without the scope a call needs gets a 403 whose WWW-Authenticate header says error="insufficient_scope" and names the scope to ask for.

0. Or skip all of this: curl -o qr.svg "https://app.qrsalt.com/api/qr/free?data=https://example.com" needs no key at all. The small print.

1. Create a key in Dashboard → API on any plan, and keep it in an environment variable, QRSALT_KEY.

2. Render a static QR code as a PNG:

• Create a dynamic code (Starter and above). The answer carries its id, shortUrl and an image URL.
• Fetch that code as an image in any format, or change its destination later with PATCH.

Errors use HTTP status codes and a JSON body with a stable code and a readable message, at the top level.

Every endpoint sends those two fields the same way: the keyed ones under /api/v1, the render endpoints and the keyless ones. One error handler that reads code and message works for all of them.

Older integrations read a field called error, so it is still sent, in two shapes.

Under /api/v1 it is an object repeating code and message and carrying anything extra: suggestedPlan on a 402, resetAt on a 429, scope or scopes on a 403.

A refusal a plan would lift (plan_required, limit_reached, and quota_exceeded below the top plan) also carries upgrade_url, inside error and at the top level. It is the page where that plan is bought, with the plan already chosen.

On the render and keyless endpoints error is the sentence itself, the same string as message. Sometimes a hint sits beside it, with a docs link to the section on the parameter you got wrong.

A blank string in an optional field means "not set", never an error: on create the default is used, on update the field is left alone.

Two fields are exceptions, because a blank there has a meaning: folderId (no folder) and slug on Update (back to the short code). Required fields also refuse a blank.

Paths under /api/v1 that do not exist answer with this body too. GET /api/v1/code (missing the s) gets a 404 with code: "not_found", never an HTML page.

That check runs before your key is read, so a typo does not count against your rate limit. A method an endpoint does not have is different: PUT /api/v1/codes/{id} answers 405 Method Not Allowed with an empty body.

A key on Starter or above can make 600 requests a minute. On a plan without API access a key can only render, and gets 60 a minute.

The count is per key, so a nightly import that uses its whole limit does not slow down a different key that your workflow tool uses.

The keyless endpoints count units of work, not requests: an SVG costs 1 unit, a PNG up to 256 pixels 2, a larger PNG 4. One caller gets 480 units an hour, and one address 4,800.

On n8n Cloud, in an office or on a campus network, many callers share one address and so share its 4,800 units an hour.

Send an X-QRSalt-Client header, 1 to 64 characters of A-Za-z0-9._-, and your calls get a budget of their own inside that ceiling.

We do not check the value, so it only splits the shared budget more fairly and gives no other access. A key gives you a limit that only you can use.

Going over answers 429 with resetAt, the time the count starts again, and a Retry-After header saying how many seconds that is.

Each workspace also has a monthly number of requests: 500 API requests a month on Starter, 5,000 on Pro and 100,000 on Business, a fair-use ceiling.

Every call under /api/v1 counts, and so does every tool call over the MCP server. The render and keyless endpoints don't.

The month is the calendar month in UTC, so the count starts again at 00:00 UTC on the 1st.

Every counted response carries X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset, and Check a key shows the same numbers as quota.

When the month is used up, calls answer 429 with code: "quota_exceeded", the limit, resetAt (the first of next month) and a Retry-After header.

On Starter and Pro the answer also names the suggestedPlan and its upgrade_url. The per-minute limit above still applies on every plan.

The same parameters always give the same image, so cache a code you use more than once instead of rendering it on every page view.

Answers with the workspace a key acts for, and what that workspace is allowed to do. Call it when somebody pastes a key in, to tell them straight away whether it works.

It also shows what the plan includes. Reading and changing the account starts on Starter, while webhooks start on Business, so a valid key may still be unable to subscribe to scans.

Read features and offer only what the plan has, so a subscribe call doesn't fail and look like a broken key.

key.scopes is the other half. Even on a plan with everything, a key without delete in that list gets a 403 from DELETE /api/v1/codes/{id}. Check both before you tell anyone their key is broken: it may just be missing a scope.

key.scopes is always what the key can do right now: what it was made with, narrowed to what the workspace’s plan sells today.

A key made on Starter keeps its permissions when the workspace goes back to Free, listed separately as key.granted and key.dormant. Dormant ones answer 402 until the plan returns, then work again with the same key.

It needs no scope, so even a render-only key can call it to check that it works. Nothing in the reply is secret: it shows the key’s prefix, which the dashboard shows too, never the key itself.

key.kind is api_key for a key and oauth for an app signed in with QRSalt, which has no prefix, so key.prefix is null for it.

Returns a QR code as an SVG or a PNG, with no key and no account. Use it to try the API from your own code before you decide anything.

Send data with the text to encode; text works too. There is no type here: build the Wi-Fi or contact-card string yourself, or use GET /api/qr with a key, which does it for you.

It has far fewer options than the keyed endpoint: SVG and PNG only, up to 512 pixels, up to 512 bytes of content, and only colour, margin and error correction for design.

Every other parameter of /api/qr (styles, eye shapes, logos, JPG, WebP, PDF, larger sizes) gets a 400 that names it. You find out on the first call instead of getting an image without the design you asked for.

The allowance is hourly and counted in units of work, not requests. Two limits apply: one for the caller and one for the address it comes from.

Rate limits has the numbers, and the X-QRSalt-Client header for callers behind a shared address. To get past them, use a Free key: it renders everything GET /api/qr renders, with a limit nobody else can spend.

Post an image and get back the text stored in the code. Like the free render, it needs no key and no account.

Post the file as the request body, or as a file field in a multipart form. PNG, JPEG and WebP, up to 12 MB, which fits a full-resolution phone photo.

Anything larger is answered 413 rather than truncated. The type is decided by the first bytes of the file, never by a header or a filename.

The image is read and then discarded. It is held in memory for the decode and dropped: no file is written, no row is created, and neither the picture nor its text is logged.

The answer is sent no-store, so it is not cached on the way back either.

There is no parameter for a URL. If we fetched any address you sent, anyone could make our servers open addresses inside our own network (server-side request forgery). If your image is behind a link, download it and post the bytes.

Before it is read the picture is shrunk so its longest side is 2048 pixels. A file whose real dimensions are over 24 megapixels is refused, so a small file can't expand into a huge image in memory.

A read costs 8 units of the keyless allowance, and one more for each extra symbology asked for. Rate limits has the numbers.

Returns a static QR code image. Send a type and that type's fields, or data with the exact text to encode. The code is not stored and has no short link; to make one you can edit later, create a dynamic code.

The API returns the QR code alone. frame and label are refused with a 400, so an integration that still sends them finds out on its first call.

Draws a barcode in one of 12 symbologies and returns the image. Nothing is stored.

The data lives in the bars, so there is nothing to re-point once it is printed. If the destination might move, use a dynamic QR code.

gs1-datamatrix takes GS1 application identifiers in brackets, like (01)09506000134352(17)271231(10)LOT42, and writes the FNC1 and separators itself. gs1datamatrix, bwip-js's own name for it, is accepted too.

Each field is checked before anything is drawn: the check digit of a GTIN, SSCC or GLN, real dates in YYMMDD (day 00 allowed), length and character set, and which fields need which.

A refusal names the field, as in (01) Product number: The check digit should be 2, not 9.

The image is the symbol alone. The human-readable lines are yours to set, or come with the download from the generator.

Saves a code to your account, as if you had made it in the dashboard: the same checks on the destination, the same plan limits and the same history. It works for every type.

Every type is dynamic by default. A website or product code redirects. A contact card, Wi-Fi, text, email, phone or SMS code opens a small page we host that does the thing, such as offering to call the number.

Either way you get a shortUrl, you can change the content later, and it counts against your plan's dynamic codes. Send kind: "STATIC" to put the content in the pattern instead.

The answer includes an image URL for the code's image, and a publicImage URL that opens without a key, for an email or a sheet. See Public image link.

An APP_STORE code is always dynamic. Its payload is appName, appStore (an apps.apple.com or other https link), googlePlay (a play.google.com details or other https link) and an optional fallback. Send at least one store link.

A scan from an iPhone or iPad goes to appStore, one from Android to googlePlay, and anything else to fallback. With no fallback, it opens a page we host with a button for each link.

A LOCATION code opens a map. Its payload is any of query (an address or place name), latitude and longitude together, or mapsLink (a Google Maps or Apple Maps link).

A static one holds a Google Maps link. A dynamic one sends an iPhone to Apple Maps and everything else to Google Maps.

An EVENT code adds a date to a calendar. Its payload is title and start (a wall-clock time, 2026-10-03T19:00), with timeZone (an IANA zone, default UTC), end (default an hour later), allDay, location, description and url.

A static one holds an iCalendar VEVENT with the times in UTC. A dynamic one opens a page we host with an .ics file, Google Calendar and Outlook.

A PAYMENT code opens a payment or tip page. Its payload is provider (paypal, venmo, cashapp, revolut, wise, bmc, stripe or other), handle, payee (the name people see), and an optional amount, currency and note.

handle is checked by that provider's own rules: a PayPal.me name, a Venmo username, a $cashtag, a Revtag, a wise.com/pay/me link, a Buy Me a Coffee page name, or a Stripe Payment Link.

A Stripe link is on buy.stripe.com, donate.stripe.com or the business's own https domain, and an other link must be https.

A dynamic one, the default, opens a page we host showing the payee beside the account before it hands over. A static one holds the provider's link itself. Every payment link is screened when the code is saved.

A PDF code needs a file uploaded in the dashboard, so it is made there. The API reads, renames, pauses, moves, files and deletes it like any other code.

Makes a short link and saves it to your account. Underneath it is a dynamic code, so everything else works on it, and you can get its QR code whenever you want.

Change where it goes with Update, route each click with Smart routing, read its clicks with Code scans and remove it with Delete. It counts against your plan’s dynamic codes.

The id that comes back answers on /api/v1/links/{id} and on /api/v1/codes/{id} alike.

GET, PATCH and DELETE are the same endpoint under either name, so a shortener integration never has to leave the links path.

Send slug to pick the ending, as in qrsalt.com/autumn-menu. On our domain that needs Business; on your own domain, Starter and above. Leave slug out and you get a random one.

An ending is 4 to 24 characters of lowercase letters, digits and hyphens, starts and ends with a letter or digit, and can't be one of our page names such as pricing.

A 7 to 10 character ending must contain a hyphen or one of 0, 1, l or o, because automatic links use that length. Once set, the ending never changes.

With domain, the link is on your custom domain, and an ending only has to be free there: go.yourbrand.com/menu works even if someone else has menu on ours. There, only a few words are kept for us, like help and pricing.

A code on your domain has two links. customUrl is the one on your domain; shortCodeUrl is its short code on ours, which always works and also answers on your domain.

shortUrl is the one to print: the custom link while your domain works, otherwise the short code, and the QR image follows it. If your domain stops verifying, warning says so, and the custom link comes back when the domain is fixed.

List your links with GET /api/v1/links, newest first, with limit (1 - 100, default 25), offset and q to search names and addresses. It answers with short links made here (output: "link") and nothing else.

List codes answers with everything you have made. Its output=link filter returns every code that has a short link, which is every dynamic code. For the QR code of any link, use Get a code's image.

One of your codes, with its short link and scan count. Another workspace's id is a 404.

scanCount and lastScanAt come from a summary we update every few minutes, so they can be up to about five minutes behind. That way they always match Code scans and Workspace analytics.

Your code as an image, with its saved colours, shapes and logo, and no frame. A dynamic code encodes its short link (on your custom domain if it has one); a static code encodes its content.

Every code comes back with a publicImage address beside image. It is the same picture at a link that opens for anyone, with no key and no Authorization header.

Use image from a program that can send your key. Use publicImage in an email, a spreadsheet cell, a Slack message or an <img src>, where nothing can send a header.

You never build this address yourself. It contains a signature, so nobody can guess it from a short link ending.

The finished URL comes back in publicImage on every code you create, get or list. It is the same address every time, so it is safe to write into a sheet.

Treat it as public. Anyone you give it to can open it and pass it on. It renders one picture and does nothing else: no name, no destination, no scan count, no JSON. The address ends .png or .svg, and size sets the width.

It stops working when the code is deleted or disabled. Delete a code and the link answers 404 from that moment, and its ending is never given to another code. A code we have disabled for abuse stops too.

A paused code keeps rendering: pausing stops the redirect, but the printed code is unchanged, so its image still works.

Because it needs no key, it has the same caps as the keyless endpoints: PNG and SVG only, up to 512 pixels, spending the same hourly allowance as the free render. For JPG, WebP, PDF and larger sizes, use the keyed endpoint.

The answer is cached publicly for five minutes behind an ETag, and carries X-Robots-Tag: noindex.

Everything you have made, newest first, a page at a time: QR codes and short links together. meta.nextOffset is the offset of the next page, or null. For the short links on their own, use GET /api/v1/links under Shorten a link.

Rename a code, change where a dynamic code points, pause and resume it, move it to a domain, change its custom link, file it, tag it or set its campaign tags. Send only what changes.

A printed dynamic code opens the new destination straight away. The old one is kept as a version you can roll back to in the dashboard.

Your key needs the delete scope, and no key has it unless somebody ticked that box. You can’t undo this call, so only a key made with that permission can make it.

The code leaves your lists, stops counting toward your plan, and can’t be restored, because we erase the record. What comes back is the code as it was just before, with status ARCHIVED, the name this API has always used for a deleted code.

What happens to the printed code depends on its kind. Scans of a dynamic code come through us, so from then on they land on a not-found page. Its short link is never handed to anyone else.

A static code has its destination in the pattern and never touches our servers. Deleting it only removes our record, and every printed copy keeps working. If you’re writing a clean-up job, check kind first.

?confirm= is optional, but we check it when you send it: it has to be the code’s name or its short link ending, or nothing is deleted.

Send it when something else decides what to delete, such as an AI model acting on text it read. The MCP connector always sends it. A workflow you wrote yourself can leave it out.

Short links are codes too, so this deletes them. DELETE /api/v1/links/{id} is the same endpoint under the shortener’s own name, for callers that have only ever made links.

A GS1 Digital Link is a URL that a till scanner and a phone camera can both read. The identifier sits in the path, so /01/05012345678900 names the product itself. You can use one here in two ways, and only the second costs money.

Free, on every plan. Put the Digital Link inside the pattern: send type: "GS1" with a payload, or call GET /api/qr?type=gs1 with any key, a free one included. The address is yours, and we store nothing.

Reading one back needs no key at all. POST /api/qr/decode splits GS1 content into its application identifiers, whether it arrives as a Digital Link, a GS1-128 or a GS1 DataMatrix.

Paid: a Digital Link we host and answer. Send gs1 when you create a code, or PATCH it onto an existing one, and the code answers on a second address of ours as well as its short link.

A printed pack then gets two things it can’t have otherwise: you can re-point it later, and its scans are counted. Starter and above.

The primary keys we host are 253, 255, 401, 402, 414, 417, 8003, 8004, 8006, 8010, 8013, 8017, 8018, 00, 01. We store a GTIN padded to 14 digits, so the 13 under a barcode and the 14 a scanner reads are one address.

Qualifiers go in qualifiers, keyed by AI (22, 10 and 21 after a GTIN), and come out in the order the standard fixes.

If the key has a check digit we verify it, and a wrong one is refused with the digit it should have ended in.

Each Digital Link belongs to one code, so if another workspace already hosts that key you get a 409. Removing one with gs1: null stops every printed copy resolving at once, so we honour ?confirm= on that request exactly as on DELETE.

We answer with a plain redirect. It isn’t a GS1-conformant resolver: there’s no linkset, no linkType and no /.well-known/gs1resolver yet, because each of those promises a set of links and a code has one destination.

Daily scans and unique visitors for one code, and one optional breakdown. City and region breakdowns come with Pro and above.

The date range can’t go back further than your plan keeps scan history, and the answer says when the range was cut short.

Scans across every code in your workspace: the same numbers as the Analytics page in the dashboard, with the same plan rules.

Change up to 500 codes in one request, as the bulk bar on the Codes page does. Send ids and an action.

Each code is checked like a single change: another workspace's id, a deleted code or one under review is skipped with a reason, and the rest go ahead.

results has one entry per id. Webhooks go out for every changed code. Bulk requests are limited to 60 an hour per workspace, on top of the per-key limit.

action: "delete" needs the delete scope instead of write: the scope follows what the request does, not the HTTP method.

It needs no confirmation, because no key has the delete scope unless somebody ticked it. Every code it deletes is gone for good, and none of their short links is ever reused.

Your folders, with how many codes each holds. POST the same path with a name to make one. One folder is read, renamed and removed at /api/v1/folders/{id}.

File codes with folderId on Create and Update, or many at once with Bulk actions.

One folder, with how many codes it holds. To see the codes themselves, use List codes with folderId.

Changes the name. The codes in it stay where they are. A name your workspace already uses is refused rather than merged into.

Removes the folder. The codes in it are not deleted: they move to no folder in the same write, and keep their destination, their short link and their scans. codesUnfiled says how many moved. The dashboard can undo it for 24 hours.

Your tags, with how many codes carry each. Tags are made by naming them: tags on a code, or add in Bulk actions. Filter the list of codes with ?tag=. One tag is read, renamed and removed at /api/v1/tags/{id}.

One tag, with how many codes carry it. For the codes themselves, use List codes with tag and the name.

Changes the word on every code that carries it. A name another tag already has is refused, not merged, because a merge would change which codes carry which tag and could not be undone. Delete one of the two tags instead.

Removes the tag and takes the word off every code that carried it. Those codes are not deleted and nothing else about them changes.

codesUntagged says how many lost the word. If your workspace moves to a plan without tags, you can still remove the tags it has.

The campaign-tag presets saved in the dashboard, for action: "utm" in Bulk actions. To set campaign tags on a single code, send the values in utm instead.

Your custom domains, with their status and the DNS records to add. meta.limit is how many your plan includes; meta.defaultDomain is the domain new codes get, or null for ours.

Each domain needs a TXT record that proves it is yours and a CNAME that points it at us. Add both at your DNS provider as dns shows them. See Custom domains for the whole flow.

Adds a domain you own, like go.yourbrand.com. It starts PENDING. Add the two records in dns; we check every few minutes, or check it now. Owners and admins only. How many domains you can add depends on your plan.

One domain, with its status, records and the number of codes on it. lastError says why the last check failed.

Checks the records now: the same check as Check DNS now in the dashboard, once every 30 seconds per domain. meta.verified says whether it passed and meta.error what is missing.

Make a verified domain the default: new codes and links get it unless you send domain. false puts new codes back on our domain. Codes you already made stay where they are. Owners and admins only.

Removes a domain. Its codes move back to our domain, where their short code always worked; copies printed with this domain stop working. When codes use it, send confirm with the hostname, as the dashboard asks you to type it. Owners and admins only.

Your QR Menus, read-only: title, public address, whether it is published, and views. Build and edit them in the dashboard.

A menu's url is on qrsalt.com, which is the one address a menu has. The old app.qrsalt.com/p/… form is permanently redirected there, so anything already stored or shared keeps working.

Your QR Forms, read-only, with their response counts. Read the answers with Form responses, or get each one as it arrives with the form.submitted webhook.

A form's answers, newest first, a page at a time. answers is keyed by question id; meta.questions names each one. Answers are personal data your form collected, so keep them as carefully as you would the CSV.

A webhook is a web address on your server. We send it a message the moment something happens, like a scan or a form answer, so your other tools find out right away.

Webhooks come with Business. Add an endpoint in Dashboard → Webhooks, pick the events, and copy its signing secret.

Subscribe an endpoint to any of these:

• code.created - A code was created
• code.updated - A code was renamed or re-pointed
• code.disabled - A code was paused, deleted or disabled
• scan.recorded - A code was scanned
• form.submitted - A QR Form was answered (the answers are included)

Each event is a POST of JSON to your URL, with x-qr-signature, x-qr-event-id (the same on every retry) and x-qr-event headers. Location is country, region and city only; no IP address leaves us.

In scan.recorded the place fields are country (an ISO 3166-1 country code, NO), regionCode and city (a name). Any of them can be null, and how precise they are depends on the phone’s network.

regionCode is the ISO 3166-2 subdivision code without its country prefix, such as 03 or CA. It is a code, which is why it is not called region.

form.submitted carries the answers, so your endpoint receives personal data your form collected (names, emails, phone numbers). Nothing identifies the person beyond what they typed.

Every question is listed in form order, with answer: null when it was skipped. An answer over 1,000 characters is cut and marked truncated; the full response is on the results page and in the CSV, matched by responseId.

Paste one of these into your server. It checks that a request is from us and less than five minutes old. Pass it the raw body, before you parse it, the x-qr-signature header and your endpoint's secret.

How it works: the header is t=<unix seconds>,v1=<hex>, and v1 is the HMAC-SHA256 of t + "." + body, keyed with the whole secret.

Answer with any 2xx within 10 seconds. Anything else is a failure.

• We send at once, then retry after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours and 6 hours — 7 attempts across about 9 hours.
• A 4xx other than 408 or 429 is not retried. Redirects are not followed.
• After the last attempt, or on 410 Gone, the endpoint is switched off and the workspace owner is emailed.
• Delivery is at least once, so deduplicate on x-qr-event-id.

Rules send the scans of one dynamic code to different places by time of day, country, region or city, device, device language, scan count, or an A/B split.

We check the list from the top. The first rule whose conditions all hold wins, and a scan no rule catches goes to the code’s own destination.

Set them with rules on Create or Update; [] removes them. They take effect within a minute on every printed copy, and we check every link in them like a destination.

You can’t route a static code: its content is in the pattern and never reaches us.

Device, country, language and dates are on every plan. Weekly schedules need Starter or above; region, city, scan counts and splits need Pro or above. A condition your plan doesn’t include gets a 402.

Location comes from the network the phone is on. Country is reliable, region and city are approximate, and a scan whose place we don’t know never matches a place condition.

Scan counts come from your analytics, a few minutes behind. In a split, somebody who rescans on the same day gets the same link as the first time.

Put your own domain on codes and links, like go.yourbrand.com/menu. Custom links on your domain come with Starter and above; a chosen ending on our domain needs Business.

• Add the domain.
• Add the TXT and CNAME records from dns at your DNS provider. On Cloudflare, set the CNAME to DNS only.
• Check it until status is VERIFIED, or wait: we check every few minutes.
• Create codes and links with domain, and slug for the custom link. Or make it the default and leave domain out.
• Move codes you already have with domain on Update, or many at once with Bulk actions.
• A custom link only has to be free on your domain. Taken is a 409, a plan without custom links is a 402, and a few words are kept for us, like help.
• Every code on your domain keeps its short code on ours. shortUrl and the QR image use the custom link while the domain is verified.
• If it stops verifying, they switch to the short code and warning is set. The custom link comes back when the domain is fixed.

Any tool with an HTTP step can call the API. Put your key in a header named Authorization with the value Bearer and your key, and use the method and URL from the endpoint you want.

• Make: add HTTP → Make a request with the same settings. Set the response to binary to save an image.
• n8n: add an HTTP Request node and a Header Auth credential for the key.
• Google Sheets or Airtable: trigger on a new row, create a dynamic code, then write its shortUrl and image back to the row.

Use SVG for websites and design tools, PNG for documents and email, JPG when a tool asks for it, WebP for small web images, and PDF for print. SVG and PDF are vector, so they stay sharp at any size.

For print, send format=pdf and the printed width in mm. Use ecc=H when a logo or a rough surface covers part of the code.

Keep the default margin of 4 modules, so phones can find the code.

The same request, a Wi-Fi QR code as a PNG, in each language. Keep the key in QRSALT_KEY.