QR code data by type

The GetQR API is in beta and is available to selected workspaces. Details may change before the general release.

Each QR code has a qrType, and the type sets what data must contain. This guide lists the format of every type, a request body that works, and what you can still change once the code is printed. The examples are request bodies for Create a QR code. Send them like this:

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "qrType": "website", "data": "https://example.com/menu", "title": "Menu" }'

All types at a glance

`qrType`	`data`	Editable after printing
`website`	http(s) URL	Yes
`feedback`	http(s) URL of the form	Yes
`payment`	Payment provider URL	Yes
`whatsapp`	`wa.me` link	Yes
`location`	Map URL	Yes
`app`	Store URL or empty, plus `link.ios` / `link.android`	Yes
`email`	`mailto:` URI	Yes
`sms`	`sms:` URI	Yes
`wifi`	`WIFI:` payload	No
`pdf`, `image`, `video`	Empty, with a `fileId`	Yes
`vcard`	vCard 3.0 text	Yes
`social`	JSON string	Yes
`multilink`	JSON string	Yes
`event`	JSON string	Yes

How a QR code resolves

Every QR code is a short link plus a payload. Two fields carry the content:

Field	What it is
`link.url`	Where the short link sends a visitor. This is the real destination for every type except `wifi`.
`data`	The type’s payload, checked against `qrType`. It is stored as sent only for `wifi`, `vcard`, `social`, `multilink`, `event` and `sms`. For every other type it only supplies `link.url`, and the stored `data` becomes the short link. Read the destination from `url` in the response.

Rules for every type:

Defaults. On create, an omitted or empty link.url becomes data, and you can leave out the whole link object. When both are sent and differ, link.url wins. Send them equal, or send only data.
What the image encodes. The image encodes the short link for every type except wifi. So you can change where a printed code leads, and its scans are tracked. A WiFi QR code encodes the network itself: you can’t change it after printing, and its scans aren’t tracked.
Schemes. link.url accepts only http:, https:, wifi:, mailto:, sms: and begin:. Anything else, including geo:, smsto:, matmsg: and tel:, gets 422 Invalid destination URL, even where data accepts it.
Empty data. An empty data skips the type check. For a redirect type, link.url must then be set, or the call gets 400 Missing destination URL.
Shape. Beyond the type check, the server doesn’t validate the payload. A JSON type only has to parse as a JSON object, and a vCard only has to start with BEGIN:VCARD.

Limits marked Builder below are what the dashboard editor enforces. The API accepts payloads that ignore them, but they may render oddly on the landing page or in the editor.

Website

qrType: "website". Dashboard guide: Website QR code.

Field	Behavior
`data`	An http(s) URL.
`link.url`	The destination. Defaults to `data`.
`fileId`	Not allowed.
Encodes	The short link, which redirects to `link.url`. Scans are tracked.
After printing	Editable. Send `data` or `link.url` to move the destination. `data` alone is enough.

Request body

{
  "qrType": "website",
  "data": "https://example.com/menu",
  "title": "Menu"
}

Errors:

422 Expected an http(s) URL, e.g. "https://example.com" for qrType "website".
422 Invalid destination URL

Feedback

qrType: "feedback". Dashboard guide: Feedback QR code. data is the http(s) URL of the feedback form, for example a Google Form or a review page. Everything else works as for Website.

Request body

{
  "qrType": "feedback",
  "data": "https://forms.gle/abc123"
}

Payment

qrType: "payment". Dashboard guide: Payment QR code. data is the provider’s payment URL, for example:

https://paypal.me/<user>/25EUR

The dashboard editor recognizes these hosts: paypal.me, paypal.com/paypalme, cash.app, venmo.com, buy.stripe.com, stripe.com, square.link and payoneer.com. For PayPal, the amount is the last path segment. Any other http(s) URL works too, but the editor won’t split it into provider and amount. Everything else works as for Website.

Request body

{
  "qrType": "payment",
  "data": "https://paypal.me/acme/25EUR"
}

qrType: "whatsapp". Dashboard guide: WhatsApp QR code. data is a wa.me link: the international number in digits without +, optionally with a prefilled text.

https://wa.me/<digits>
https://wa.me/<digits>?text=<urlencoded>

The server only checks for an http(s) URL. The dashboard also reads api.whatsapp.com/send links. Everything else works as for Website.

Request body

{
  "qrType": "whatsapp",
  "data": "https://wa.me/14155550123?text=Hi%20there"
}

Location

qrType: "location". Dashboard guide: Location QR code. data is a map URL. Use this format to keep the QR code editable in the dashboard (query_place_id is optional):

https://www.google.com/maps/search/?api=1&query=<address>&query_place_coords=<lat>,<lng>&query_place_id=<id>

Any other http(s) URL also redirects. A geo: URI passes the data check but is rejected as a destination, so don’t use it. Everything else works as for Website.

Request body

{
  "qrType": "location",
  "data": "https://www.google.com/maps/search/?api=1&query=Golden+Gate+Bridge&query_place_coords=37.8199,-122.4783"
}

App Link

qrType: "app". Dashboard guide: App Link QR code.

Field	Behavior
`link.ios`, `link.android`	App Store and Google Play URLs. iOS visitors go to `ios`, Android visitors to `android`. These win over everything else at scan time.
`link.url`	The fallback for other devices. Defaults to `data`, then to `ios` or `android`.
`data`	An http(s) URL (the dashboard sends the store URL), or empty. At least one of `link.ios`, `link.android`, `link.url` or `data` must be set, or the call gets `400 Missing destination URL`.
`fileId`	Not allowed.
Encodes	The short link. Scans are tracked.
After printing	Editable. `link.ios` and `link.android` are applied independently, each only when sent. `null` clears one. You don’t have to resend `qrType`. Switching to another type clears both store links.

Request body

{
  "qrType": "app",
  "data": "https://apps.apple.com/app/id123456789",
  "link": {
    "ios": "https://apps.apple.com/app/id123456789",
    "android": "https://play.google.com/store/apps/details?id=com.acme.app"
  }
}

Errors:

422 Invalid URL
400 Missing destination URL

Email

qrType: "email". Dashboard guide: Email QR code.

mailto:<address>?subject=<subject>&body=<body>

Field	Behavior
`data`	A `mailto:` URI with an optional subject and body. Encode spaces as `%20`: the dashboard writes them as `+`, which not every mail app reads as a space. `matmsg:` is rejected as a destination.
`link.url`	The `mailto:` URI. Defaults to `data`.
`fileId`	Not allowed.
Encodes	The short link, which opens a page that hands off to the mail app.
After printing	Editable. Send `data` or `link.url` to change the message. `data` alone is enough.

Request body

{
  "qrType": "email",
  "data": "mailto:[email protected]?subject=Hello&body=Hi%20there"
}

Errors:

422 Expected a mailto URI, e.g. "mailto:[email protected]?subject=Hello" for qrType "email".

SMS

qrType: "sms". Dashboard guide: SMS QR code.

sms:+<digits>
sms:+<digits>?body=<encodeURIComponent(text)>

Field	Behavior
`data`	An `sms:` URI with an optional body. The dashboard reads only this exact form. `smsto:` is rejected as a destination.
`link.url`	The `sms:` URI. Defaults to `data`.
`fileId`	Not allowed.
Encodes	The short link, which opens a page that hands off to the messaging app.
After printing	Editable. Send `data` or `link.url` to change the message. `data` alone is enough.

Request body

{
  "qrType": "sms",
  "data": "sms:+14155550123?body=Table%2012"
}

Errors:

422 Expected an SMS URI, e.g. "sms:+14155550123?body=Hello" for qrType "sms".

WiFi

qrType: "wifi". Dashboard guide: WiFi QR code.

WIFI:T:<WPA|WEP|nopass>;S:<ssid>;P:<password>;H:<true|false>;;

Field	Behavior
`data`	Required. Keep the order `T`, `S`, `P`, `H`: the dashboard editor and list depend on it. Escape `\`, `;`, `"` and `:` in the SSID and password with a backslash. For an open network, use `T:nopass` with an empty `P:`. Scanners reject `T:none`. Builder: SSID required, password at least 8 characters unless `nopass`.
`link.url`	Not used for scanning. Defaults to `data`.
`fileId`	Not allowed.
Encodes	The raw `WIFI:` payload, not the short link. Scans aren’t tracked.
After printing	Not editable. A new `data` only changes future downloads. Printed codes keep the old network.

Request body

{
  "qrType": "wifi",
  "data": "WIFI:T:WPA;S:Cafe Guest;P:espresso42;H:false;;"
}

Errors:

422 Expected a Wi-Fi payload, e.g. "WIFI:T:WPA;S:MyNetwork;P:secret;H:false;" for qrType "wifi".

Don’t switch the type of a printed WiFi QR code. The printed codes keep the old network.

PDF, image and video

qrType: "pdf", "image" or "video". Dashboard guides: PDF, Image, Video.

Field	Behavior
`fileId`	The file. Upload it with the target that matches the type: `pdf`, `image` or `video`. With a `fileId`, `link.url` becomes the file’s URL, and anything you send in it is ignored.
`data`	Anything except another type’s payload (`WIFI:`, `BEGIN:VCARD`, `sms:`, `mailto:`, a JSON object). Empty is fine.
`link.url`	Without a `fileId`, `link.url` (or `data`) is used as an external destination. That works, but the dashboard shows no file.
Encodes	The short link, which redirects straight to the file. A PDF opens as the raw file, not in a viewer page.
After printing	Editable. Send a new `fileId` to replace the file. The old one is released.

One file per QR code: PDF bundles and image galleries aren’t available on the API. See Not supported via the API.

{
  "qrType": "pdf",
  "data": "",
  "fileId": "file_9f8e7d6c5b4a",
  "title": "Brochure"
}

{
  "qrType": "image",
  "data": "",
  "fileId": "file_3c2b1a0f9e8d",
  "title": "Floor plan"
}

{
  "qrType": "video",
  "data": "",
  "fileId": "file_5e4d3c2b1a0f",
  "title": "Product demo"
}

To upload the file and get its fileId, see Files.

vCard

qrType: "vcard". Dashboard guide: vCard QR code.

Field	Behavior
`data`	Required. vCard 3.0 text starting with `BEGIN:VCARD`, lines separated by `\r\n` (`\n` also works).
`fileId`	Optional profile image (`logo` target), used when `data` has no `PHOTO` or `X-GETQR-IMAGE-FILEID` line.
`link.url`	Ignored and replaced with the hosted page. Leave it out.
Encodes	The short link, which opens the hosted contact page with a save-contact (`.vcf`) download.
After printing	Editable. Send new `data` to update the page.

The landing page and editor read only the line forms below. Other variants, such as TEL;CELL: or EMAIL;TYPE=INTERNET:, are stored but don’t appear on the page.

N:<last>;<first>;;;: last and first name. Builder: both required, up to 40 characters.
FN:<first> <last>: not read by the page. The dashboard list label comes from it.
ORG:<company> and TITLE:<role>: company and role. Builder: up to 40 characters.
TEL;TYPE=HOME:, TEL;TYPE=CELL:, TEL;TYPE=WORK:, TEL;TYPE=FAX:: phone, mobile, work and fax numbers (+ and digits).
EMAIL:<email>: email address.
URL:<url>: website.
NOTE:<text>: summary. Escape \\, \n, \; and \,. Builder: up to 200 characters.
ADR:;;<street>;<city>;<state>;<zip>;<country>: address.
X-SOCIALPROFILE;TYPE=<platform>:<url> or URL;TYPE=<PLATFORM>:<url>: social links, one line per platform.
PHOTO;VALUE=URI:<url>: profile image URL. Wins over any file ID.
X-GETQR-IMAGE-FILEID:<fileId>: profile image (logo target).
X-GETQR-PAGE-LOGO-FILEID:<fileId>: page logo (logo target).
X-GETQR-LANDING-THEME:p|<0-4> or X-GETQR-LANDING-THEME:c|#RRGGBB|#RRGGBB|#RRGGBB: landing theme, either a preset index (0 to 4) or custom background, button and icon colors.

Social platforms: facebook, whatsapp, instagram, youtube, tiktok, messenger, snapchat, linkedin, x, reddit, pinterest, telegram, wechat, viber, line.

Request body

{
  "qrType": "vcard",
  "data": "BEGIN:VCARD\r\nVERSION:3.0\r\nN:Doe;Jane;;;\r\nFN:Jane Doe\r\nORG:Acme\r\nTITLE:CTO\r\nTEL;TYPE=CELL:+14155550123\r\nEMAIL:[email protected]\r\nURL:https://acme.com\r\nX-GETQR-LANDING-THEME:p|0\r\nEND:VCARD",
  "title": "Jane Doe"
}

Errors:

422 Expected a vCard payload starting with "BEGIN:VCARD" for qrType "vcard".

qrType: "social". Dashboard guide: Social Media QR code.

Field	Behavior
`data`	Required. A JSON string encoding an object. Build it with `JSON.stringify`.
`fileId`	Optional top-level profile image (`logo` target).
`link.url`	Ignored and replaced with the hosted page. Leave it out.
Encodes	The short link, which opens the hosted social page.
After printing	Editable. Send new `data` to update the page.

Fields in data:

Field	Type	Notes
`firstName`	string	Page headline and the only name shown. Builder: required, up to 40.
`lastName`	string	Up to 40. Not shown on the page.
`summary`	string	Up to 200.
`socialLinks`	`{ platform, url }[]`	`platform` is one of the vCard social platforms. Builder: each platform once.
`customItems`	`{ name, url, logoFileId }[]`	Builder: `name` up to 40, an http(s) `url` and a `logoFileId`. At least one social link or custom item in total.
`fileId`	string	Profile image (`logo` target). The top-level `fileId` is the fallback.
`imageUrl`	string	External profile image URL, used only when there’s no file ID.
`pageLogoFileId`	string	Page logo (`logo` target).
`landingThemeMode`	`"preset" \| "custom"`	Defaults to `preset`.
`landingPresetIndex`	0–4	Defaults to 0.
`landingCustomBg`, `landingCustomButton`, `landingCustomIcon`	`#RRGGBB`	Used when the mode is `custom`.

Request body

{
  "qrType": "social",
  "data": "{\"firstName\":\"Acme Coffee\",\"summary\":\"Follow us\",\"socialLinks\":[{\"platform\":\"instagram\",\"url\":\"https://instagram.com/acme\"}],\"customItems\":[]}"
}

Errors:

422 Expected a JSON object describing the social profile page for qrType "social".

Multi-Link

qrType: "multilink". Dashboard guide: Multi-Link QR code.

Field	Behavior
`data`	Required. A JSON string encoding an object.
`fileId`	Optional top-level profile image (`logo` target).
`link.url`	Ignored and replaced with the hosted page. Leave it out.
Encodes	The short link, which opens the hosted multi-link page.
After printing	Editable. Send new `data` to update the page.

The fields in data are those of Social Media, except that firstName, lastName and summary are replaced by:

Field	Type	Notes
`title`	string	Page heading. Builder: required, up to 40.
`description`	string	Up to 200.

In customItems, logoFileId is optional: a fallback icon is shown. Builder: at least one social link or one non-empty custom item.

Request body

{
  "qrType": "multilink",
  "data": "{\"title\":\"Acme links\",\"description\":\"Everything in one place\",\"socialLinks\":[],\"customItems\":[{\"name\":\"Shop\",\"url\":\"https://acme.com/shop\",\"logoFileId\":\"\"}]}"
}

Errors:

422 Expected a JSON object describing the multi-link page for qrType "multilink".

Event

qrType: "event". Dashboard guide: Event QR code.

Field	Behavior
`data`	Required. A JSON string encoding an object. Unknown or invalid values fall back to defaults.
`fileId`	Validated (`logo` target) and stored, but the event page reads its cover only from `data.fileId`. Put the cover ID in the payload.
`link.url`	Ignored and replaced with the hosted page. Leave it out.
Encodes	The short link, which opens the hosted event page with an `.ics` download.
After printing	Editable. Send new `data` to update the page.

Fields in data:

Field	Type	Notes
`name`	string	Builder: required.
`eventType`	string	One of the event types below, or empty.
`start`, `end`	`"YYYY-MM-DDTHH:mm"`	Wall-clock time in `timezone`. Builder: both required, end after start.
`timezone`	IANA, for example `"Europe/Berlin"`	Places start and end in the `.ics` file. Always send it: an empty or unknown zone makes the `.ics` treat the times as UTC.
`street`, `zip`, `city`, `state`, `country`	string	Builder: `city` and `country` required, up to 40 each.
`facilities`	string[]	IDs from the list below. Unknown IDs are dropped.
`notes`	string	Free text.
`fileId`	string	Cover image (`logo` target).
`pageLogoFileId`	string	Page logo (`logo` target).
`organizerName`, `organizerEmail`, `mobile`, `work`	string	`mobile` and `work` up to 40.
`socialLinks`	`{ platform, url }[]`	The vCard social platforms, plus `website`.
`ticketsUrl`	http(s) URL	Link to buy tickets.
`ticketsLabel`	string	Up to 20 characters. Longer labels are cut off. Empty shows the default label.

Event types

conference, seminar, workshop, training, webinar, meetup, networking, corporateEvent, productLaunch, tradeShow, jobFair, fundraiser, charity, wedding, engagement, birthday, anniversary, babyShower, graduation, reunion, party, religious, funeralMemorial, ceremony, concert, festival, clubNight, theater, comedy, filmScreening, exhibition, sports, tournament, raceMarathon, fitnessClass, foodDrink, market, openHouse, community, schoolEvent, kids, travelTour

Facilities

Group	IDs
Entry	`freeEntry`, `idRequired`, `invitationOnly`, `plusOneAllowed`, `reEntryAllowed`
Age (pick one)	`adultsOnly`, `age18Plus`, `age21Plus`, `kidsWelcome`
On site	`parking`, `publicTransport`, `shuttle`, `wheelchairAccess`, `evCharging`, `wifi`, `foodDrinks`, `alcoholServed`, `atm`, `coatCheck`, `pool`, `phoneCharging`, `firstAid`, `wc`
Rules	`petsAllowed`, `noPets`, `smokingArea`, `noSmoking`, `noPhotos`
Dress code (pick one)	`dressCasual`, `dressSmartCasual`, `dressBusiness`, `dressCocktail`, `dressThemed`

Request body

{
  "qrType": "event",
  "data": "{\"name\":\"Launch party\",\"eventType\":\"productLaunch\",\"start\":\"2026-11-20T18:00\",\"end\":\"2026-11-20T22:00\",\"timezone\":\"Europe/Berlin\",\"city\":\"Berlin\",\"country\":\"Germany\",\"facilities\":[\"freeEntry\"],\"socialLinks\":[],\"ticketsUrl\":\"https://acme.com/tickets\"}"
}

Errors:

422 Expected a JSON object describing the event page for qrType "event".

Files in QR codes

pdf, image, video. The content of a PDF, image or video QR code.
logo. Profile images, page logos, custom-link icons and center logos.

Files that are never attached to a QR code are deleted after a grace period. fileId errors, returned on create and on PATCH when fileId is sent:

Status	Cause
`422 unprocessable_entity`	The type takes no file. Only `pdf`, `image`, `video`, `vcard`, `social`, `multilink` and `event` accept one.
`404 not_found`	No file with this ID. Register it with `POST /api/v1/files` first.
`422 unprocessable_entity`	The file was uploaded for a different target. For example, an `image` upload on a PDF QR code, or a `pdf`, `image` or `video` upload used as a vCard photo.
`422 unprocessable_entity`	The file is registered, but the upload to `uploadUrl` never completed.

File IDs inside a payload (fileId, pageLogoFileId, customItems[].logoFileId, X-GETQR-*-FILEID lines) aren’t validated. They only render when uploaded with the logo target. The QR code claims them, so cleanup leaves them alone.

Switching type

You can change qrType with Update a QR code. Send data that matches the new type: the stored payload belongs to the old type, so a switch without it is rejected. After an update, the destination is resolved in this order:

vcard, social, multilink, event: always the hosted page.
A PDF bundle or image gallery made in the dashboard: its landing page.
pdf, image, video: the file URL (a new fileId, else the stored one).
link.url, when sent.
Changed data.
The stored URL.

What each switch does:

Out of pdf, image or video. fileId and any bundle or gallery are cleared.
Into pdf, image or video. Send fileId too, or the stored one is reused, which may be a vCard photo.
Out of app. The app name, link.ios and link.android are cleared, so phones follow the new destination.
Into wifi. The image switches to the raw payload. Codes already printed still hold the short link, which now redirects to a wifi: URL.
Out of wifi. Printed codes keep their old network.
Into vcard, social, multilink or event. The short link is pointed at the new hosted page.
Out of vcard, social, multilink or event. Send the new data. The destination follows it.

Static QR codes made in the dashboard have no short link, so changing their link.url gets 422.

Not supported via the API

These dashboard features aren’t part of the v1 API. Unknown fields are dropped without an error, so sending them has no effect.

Field	Description
`appName`	The display name of an App Link QR code. App Link QR codes created through the API show their store URL in the dashboard list.
`isStatic`	A static QR code without a short link. Every QR code the API creates has one, so it can be edited and tracked after printing (except `wifi`).
`pdfBundle`	A PDF QR code with two or more files. The API creates single-file PDF QR codes only.
`imageGallery`	An Image QR code with two or more images. The API creates single-image QR codes only.

Bundles and galleries made in the dashboard can still be read, paused and deleted through the API, but their files can’t be changed through it.

Common issues

422 Invalid destination URL

link.url uses a scheme the short link can’t redirect to, such as geo:, smsto:, matmsg: or tel:. Use the formats on this page.

400 Missing destination URL

data is empty and there is no link.url. For app, set at least one of link.ios, link.android, link.url or data.

The response data is a short link, not my URL

For link types, the stored data is the short link. Read the destination from url.

The landing page is missing details from my payload

The page reads only the fields and line forms listed for the type. Other fields are stored but not shown.

API

QR code data by type

All types at a glance

How a QR code resolves

Website

Feedback

Payment

WhatsApp

Location

App Link

Email

SMS

WiFi

PDF, image and video

vCard

Multi-Link

Event

Files in QR codes

Switching type

Not supported via the API

Common issues

What’s next

QR codes

Files

Customization

Access rules

​All types at a glance

​How a QR code resolves

​Website

​Feedback

​Payment

​WhatsApp

​Location

​App Link

​Email

​SMS

​WiFi

​PDF, image and video

​vCard

​Social Media

​Multi-Link

​Event

​Files in QR codes

​Switching type

​Not supported via the API

​Common issues

​What’s next

QR codes

Files

Customization

Access rules

All types at a glance

How a QR code resolves

Website

Feedback

Payment

WhatsApp

Location

App Link

Email

SMS

WiFi

PDF, image and video

vCard

Social Media

Multi-Link

Event

Files in QR codes

Switching type

Not supported via the API

Common issues

What’s next