QR Code API
API docs by Redocly

QR Code API (2.0.0)

Download OpenAPI specification:Download

This is the API documentation summary of the QR Planet API.

This page contains the documentation on how to use the QR Code API through API calls.

API v2 versus API v1

It is recommended to use the v2 API for all new projects.

However, not all endpoints are already available in v2.

Therefore, if you need endpoints that are not available yet please use the v1 version for that area in the meantime.

Examples of areas that are not yet in the v2 API:

  • GS1 QR codes
  • Coupons
  • Templates
  • Leads
  • Custom variables
  • Business Cards

You can find the v1 API docs in the QR Code Portal in the menu API.

Authentication

  • All but the /health endpoint require authentication.
  • To become authenticated you will need to use either a public, or secret token.
  • You find those tokens when you click on the API menu in the QR Code Portal
  • The secret API key can be used for every endpoint. Use it only in server-to-server communication.
  • The public API key can usually only be used for reading endpoints (GET). It should be used for asynchronous GET requests in the browser (client-server communication via Javascript).

Example to list your QR Codes (secret and public key can be used):

curl -X 'GET' \
  'https://api.qrpci.com/api/v2/qrcodes?type=URL&page=1&size=50' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer public:yourdomain.com:xxxx:yyyyyyyyy'

Example to create a QR Code (only secret key can be used):

curl -X 'POST' \
  'http://api.qrpci.com/api/v2/qrcodes' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer secret:yourdomain.com:xxxx:yyyyyyyyy' \
  -H 'Content-Type: application/json' \
  -d '{
  "target_url": "https://test.com",
  "slug": "easter-promotion-2"
}'

QR Codes

In this area you find all the API endpoints to manage your QR codes:

  • create, get details and delete a QR code
  • list your QR codes
  • get and remove country/language based QR code target urls
  • get and reset statistics of the scans of your QR codes
  • etc.

List QR Codes

Returns a paginated list of your QR codes.

Authorizations:
HTTPBearer
query Parameters
QRCodeType (string) or Type (null) (Type)

Filter by QR code type (exact match) - example: URL

QRCodeSubType (string) or Subtype (null) (Subtype)

Filter by QR code subtype (exact match) - example: QRCodeSubType.URL

Code Like (string) or Code Like (null) (Code Like)

Filter by QR code code (partial match) - example: easter-promotion-2

Medium (string) or Medium (null) (Medium)

Filter by medium (exact match) - example: FLYER

Folder (string) or Folder (null) (Folder)

Filter by folder (exact match) - example: folder1

Tag (string) or Tag (null) (Tag)

Filter by tag (exact match) - example: tag1

Title (string) or Title (null) (Title)

Filter by title (exact match) - example: Easter Promotion 2 2025

Title Like (string) or Title Like (null) (Title Like)

Filter by title (partial match) - example: Easter Promotion

Description (string) or Description (null) (Description)

Filter by description (exact match) - example: Welcome to our Easter Promotion Relaunch 2025

Description Like (string) or Description Like (null) (Description Like)

Filter by description (partial match) - example: Promotion Relaunch

Target Url (string) or Target Url (null) (Target Url)

Filter by target url (exact match) - example: https://test.com

Target Url Like (string) or Target Url Like (null) (Target Url Like)

Filter by target url (partial match) - example: test.com

Scan Count From (string) or Scan Count From (null) (Scan Count From)

Filter number of scans of the QR code from this value (inclusive) - example: 100

Scan Count To (string) or Scan Count To (null) (Scan Count To)

Filter number of scans of the QR code up to this value (inclusive) - example: 200

Unique Visitor Count From (string) or Unique Visitor Count From (null) (Unique Visitor Count From)

Filter number of unique visitors of the QR code from this value (inclusive) - example: 50

Unique Visitor Count To (string) or Unique Visitor Count To (null) (Unique Visitor Count To)

Filter number of unique visitors of the QR code up to this value (inclusive) - example: 100

Notify Email (boolean) or Notify Email (null) (Notify Email)

Filter if the notification for emails is active - example: true

Notify Sms (boolean) or Notify Sms (null) (Notify Sms)

Filter if the notification for emails is active - example: true

Creation At From (string) or Creation At From (null) (Creation At From)

Filter creation date of QR code from this datetime (inclusive) - example: 2025-09-27 00:00:01

Creation At To (string) or Creation At To (null) (Creation At To)

Filter creation date of QR code up to this datetime (inclusive) - example: 2025-09-27 23:59:59

Last Edit At From (string) or Last Edit At From (null) (Last Edit At From)

Filter last edit of QR code from this datetime (inclusive) - example: 2025-09-27 00:00:01

Last Edit At To (string) or Last Edit At To (null) (Last Edit At To)

Filter last edit of QR code up to this datetime (inclusive) - example: 2025-09-27 23:59:59

First Scan At From (string) or First Scan At From (null) (First Scan At From)

Filter first scan of QR code from this datetime (inclusive) - example: 2025-09-27 00:00:01

First Scan At To (string) or First Scan At To (null) (First Scan At To)

Filter first scan of QR code up to this datetime (inclusive) - example: 2025-09-27 23:59:59

Last Scan At From (string) or Last Scan At From (null) (Last Scan At From)

Filter last scan of QR code from this datetime (inclusive) - example: 2025-09-27 00:00:01

Last Scan At To (string) or Last Scan At To (null) (Last Scan At To)

Filter last scan of QR code up to this datetime (inclusive) - example: 2025-09-27 23:59:59

page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 50

Page size

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "pages": 0
}

Create a QR code

Creates a dynamic or static QR Code.

Be aware that only for dynamic QR codes analytics are available and the target url can be changed later.

You find some common examples below:

Use Case Values
Dynamic: Simplest form of a QR code target_url = https://test.com
Dynamic: With custom slug target_url = https://test.com, slug = easter-promotion-2
Static: URL (!) static = True, content = https://mystaticwebsite.com
Static: Phone number static = True, content = +18552700999
Static: SMS static = True, content = SMSTO:+18552700999:This is my sms text message
Static: Email static = True, content = MATMSG:TO:[email protected];SUB:mysubject;BODY:my email message text;;
Static: Wifi static = True, content = WIFI:S:myssid;T:WPA;P:mypassword;;
Static: Bitcoin static = True, content = bitcoin:16sym9PubRco4nekDa2ZC9VYZuSwzSc999?amount=0.1
Static: SEPA static = True, content = DE89 3704 0044 0532 0130 00
Authorizations:
HTTPBearer
Request Body schema: application/json
required
Static (boolean) or Static (null) (Static)
Default: false

Indicates if it should be a static QR code instead of the default dynamic QR code. In case of a dynamic QR code the target url is provided in the field target_url. In case of static QR code the content is stored in field content and is directly encoded into the QR code.

target_url
string (Target Url)

The target url the dynamic QR code redirects to.

content
string (Content)

The actual content of a static QR code like phone number or email address.

Slug (string) or Slug (null) (Slug)

An (optional) custom slug you want to use like easter-promotion-2 which leads to a final Short URL like https://qr.yourdomain.com/easter-promotion-2 (dependent on the domain you are using in your account). If not specified a random alphanumeric hash-value is being used for the Short URL like https://qr.yourdomain.com/ydr39. In the rest of the API you can access the QR code then via this slug in the code path parameter like GET /api/v2/qrcodes/{code}. This is also sometimes referred to as Vanity URL in the frontend UI.

Title (string) or Title (null) (Title)

The title of the target website that is shown when displaying the QR code in the QR code portal. If not specified the title of the target url is going to be used.

Description (string) or Description (null) (Description)

The description of the target website that is shown when displaying the QR code in the QR code portal. If not specified the meta description of the target url is going to be used. The description can also be a JSON string.

Metadata (object) or Metadata (null) (Metadata)

Additional metadata as JSON object. The following reserved keys add the following parameters when forwarded:

Reserved key Meaning
{"origin":"1"} 2-digit country code where QR code was scanned
{"region":"1"} Region where QR code was scanned
{"lang":"1"} Set language on the device from which the QR code was scanned
{"tags":"1"} Tags assigned to the QR code

If this metadata field is used, the description field cannot be used!

Gps (boolean) or Gps (null) (Gps)
Default: false

Indicates if the GPS tracking is active.

Notify Email (boolean) or Notify Email (null) (Notify Email)
Default: false

Indicates that the email notification is active when the QR Code is scanned

Notify Sms (boolean) or Notify Sms (null) (Notify Sms)
Default: false

Indicates that the sms notification is active when the QR Code is scanned

Medium (string) or Medium (null) (Medium)

A medium on which the QR Code will be printed can be specified. There are predefined medias like NEWSPAPER, PRODUCT, FLYER, POSTER, BUSINESS_CARD, PRODUCT_FOLDER, SHOPPING_WINDOW, WEBSITE, TV. However this field can contain any alpha-numeric string e.g. T-Shirt.

Folder Id (string) or Folder Id (null) (Folder Id)

Folder id where the QR code is stored.

Password (string) or Password (null) (Password)

If you add the optional parameter password a user has to type in the correct password before he is being redirected to the target URL.

LocationData (object) or null

Geodata can be transmitted with each QR code. This could be, for example, the company's website address or any location where the QR code is placed. The address parameter is a human-readable address. The lat (latitude) and lng (longitude) parameters are intended for automated processing, such as displaying the location on a map. The image parameter allows you to specify the path to a suitable image.

Responses

Request samples

Content type
application/json
Example

Here you just provide the targt url.

{}

Response samples

Content type
application/json
{}

Delete ALL QR Codes

Deletes ALL QR Codes of this user. Be careful, this operation cannot be undone!

Authorizations:
HTTPBearer
query Parameters
confirm
required
string (Confirm)

Must be 'DELETE_ALL' to confirm. This is a security measure.

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Get a QR Code

Returns a single QR code by its unique identifier.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Responses

Response samples

Content type
application/json
{
  • "code": "easter-promotion-2",
  • "short_url": "https://qr.yourdomain.com/easter-promotion-2",
  • "static": false,
  • "target_url": "https://test.com",
  • "content": "",
  • "type": "URL",
  • "subtype": "URL",
  • "folder_id": "4711",
  • "folder_name": "folder1",
  • "tags": [
    ],
  • "qr_code_image_url": "https://qr.yourdomain.com/i/easter-promotion-2",
  • "title": "Easter Promotion 2 2025",
  • "description": "Welcome to our Easter Promotion Relaunch 2025",
  • "scan_count": 12,
  • "unique_visitor_count": 10,
  • "creation_at": "2025-09-15 15:22:09",
  • "gs1_slug": "01/00123456789012",
  • "location": {
    },
  • "metadata": {
    },
  • "medium": "FLYER",
  • "last_edit_at": "2025-09-15 15:22:09",
  • "first_scan_at": "2025-09-15 15:22:09",
  • "last_scan_at": "2025-09-15 15:22:09"
}

Delete a QR Code

Deletes a QR Code identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Change certain fields of a QR Code

Change certain fields of a QR Code identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Request Body schema: application/json
required
Target Url (string) or Target Url (null) (Target Url)

The target url the dynamic QR code redirects to.

Title (string) or Title (null) (Title)

The title of the target website that is shown when displaying the QR code in the QR code portal. If not specified the title of the target url is going to be used.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": "easter-promotion-2",
  • "short_url": "https://qr.yourdomain.com/easter-promotion-2",
  • "static": false,
  • "target_url": "https://test.com",
  • "content": "",
  • "type": "URL",
  • "subtype": "URL",
  • "folder_id": "4711",
  • "folder_name": "folder1",
  • "tags": [
    ],
  • "qr_code_image_url": "https://qr.yourdomain.com/i/easter-promotion-2",
  • "title": "Easter Promotion 2 2025",
  • "description": "Welcome to our Easter Promotion Relaunch 2025",
  • "scan_count": 12,
  • "unique_visitor_count": 10,
  • "creation_at": "2025-09-15 15:22:09",
  • "gs1_slug": "01/00123456789012",
  • "location": {
    },
  • "metadata": {
    },
  • "medium": "FLYER",
  • "last_edit_at": "2025-09-15 15:22:09",
  • "first_scan_at": "2025-09-15 15:22:09",
  • "last_scan_at": "2025-09-15 15:22:09"
}

Download the image of a QR Code without a Designer QR code template

Download the image of a QR Code in black/white without a Designer QR code template

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

query Parameters
ImageFormatBasic (string) or Format (null) (Format)
Default: "PNG"

The format the generated image should have - example: PNG

size
integer (Size) [ 1 .. 30 ]
Default: 10

Size of the image from 1-30 (only relevant for PNG) - example: 30

ErrorCorrectionLevel (string) or Error Correction Level (null) (Error Correction Level)
Default: "L"

The error correction level (L, M, Q, H) - example: L

padding
integer (Padding) [ 0 .. 30 ]
Default: 4

Padding around the QR code - example: 4

Show Title (boolean) or Show Title (null) (Show Title)
Default: false

Show the title of the QR code below the image - example: false

Responses

Response samples

Content type
application/json
null

Get the statistics of a QR Code

Get the QR Code statistics identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

query Parameters
Country Code (string) or Country Code (null) (Country Code)

Filter by country code (exact match) - example: DE

Scan Date From (string) or Scan Date From (null) (Scan Date From)

Filter scans of QR code from this date (inclusive) - example: 2025-09-27

Scan Date To (string) or Scan Date To (null) (Scan Date To)

Filter scans of QR code up to this date (inclusive) - example: 2025-09-30

DateRelativeRange (string) or Scan Date Relative Range (null) (Scan Date Relative Range)

Filter scans of QR code via a relative day range selector

SortOrder (string) or Sort Order (null) (Sort Order)

Sort the result by scan date ascending or descending

page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "summary": {
    },
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "total": 0,
  • "pages": 0
}

Resets the statistics of a QR Code

Resets the QR Code statistics identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Get the tags of a QR Code

Get the tags that have been assigned to a QR code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Responses

Response samples

Content type
application/json
{
  • "code": "easter-promotion-2",
  • "tags": [
    ]
}

Change the tags of a QR Code

Change the tags of a QR Code identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Request Body schema: application/json
required
tags_to_add
Array of strings (Tags To Add)

Tags to add to the QR code.

tags_to_remove
Array of strings (Tags To Remove)

Tags to remove from the QR code.

Responses

Request samples

Content type
application/json
{
  • "tags_to_add": [
    ],
  • "tags_to_remove": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "easter-promotion-2",
  • "tags": [
    ]
}

Remove all tags of a QR Code

Remove all the tags of a QR Code identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Add a country-specific target to a QR Code

Add a country specific target URL to a QR code identified by its code. If the QR code gets scanned in a specific country then the user gets forwarded to this target url.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Request Body schema: application/json
required
country_code
string (Country Code)

2-letter country code

target_url
string (Target Url)

The target url the dynamic QR code redirects to.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": "easter-promotion-2",
  • "country_code": "IT",
  • "target_url": "https://test.com"
}

Remove a country-specific target of a QR Code

Remove a country specific target URL to a QR code identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

country_code
required
string (Country Code)

2-letter country code - example: IT

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Add a language-specific target to a QR Code

Add a language-specific target URL to a QR code identified by its code. If the QR code gets scanned with a device in a certain language then the user gets forwarded to this target url.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Request Body schema: application/json
required
language_code
string (Language Code)

2-letter language code

target_url
string (Target Url)

The target url the dynamic QR code redirects to.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": "easter-promotion-2",
  • "language_code": "IT",
  • "target_url": "https://test.com"
}

Remove a language-specific target of a QR Code

Remove a language-specific target URL to a QR code identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

language_code
required
string (Language Code)

2-letter language code - example: IT

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Change the type of a QR Code

Change the type and target url of the QR Code identified by its code.

Authorizations:
HTTPBearer
path Parameters
code
required
string (Code)

Code that identifies a QR code - example: easter-promotion-2

Request Body schema: application/json
required
type
string (Type)
Default: "URL"
Enum: "URL" "BUSINESS_CARD" "PRODUCT" "OPENIMMO" "COUPON" "PLAIN" "POSTER" "SYNC" "LEAD" "SOCIAL" "TRACING"

This is the QR Code type (default is URL). Allowed values: ['URL', 'BUSINESS_CARD', 'PRODUCT', 'OPENIMMO', 'COUPON', 'PLAIN', 'POSTER', 'SYNC', 'LEAD', 'SOCIAL', 'TRACING']

target_url
string (Target Url)

The target url the dynamic QR code redirects to.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Folders

In this area you find all the API endpoints to manage your QR code folders:

  • create, delete and list your folders
  • get and reset statistics of your QR code folders.

List Folders

Returns a paginated list of your folders.

Authorizations:
HTTPBearer
query Parameters
type
string (FolderType)
Enum: "QR_CODE" "LANDING_PAGE"

- example: QR_CODE

page
integer (Page) >= 1
Default: 1

Page number

size
integer (Size) [ 1 .. 100 ]
Default: 50

Page size

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "page": 1,
  • "size": 1,
  • "pages": 0
}

Create a Folder

Create a folder to house either your QR codes or Landing Pages.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
name
string (Name)

Name of a folder.

type
string (FolderType)
Enum: "QR_CODE" "LANDING_PAGE"

Type of a folder.

Parent Id (string) or Parent Id (null) (Parent Id)

Unique identifier of the parent folder.

Responses

Request samples

Content type
application/json
{
  • "name": "XMAS Promotion",
  • "type": "QR_CODE",
  • "parent_id": "12345"
}

Response samples

Content type
application/json
{
  • "id": "12345",
  • "name": "XMAS Promotion",
  • "type": "QR_CODE",
  • "parent_id": "12345"
}

Get a folder

Returns a single folder by its unique identifier.

Authorizations:
HTTPBearer
path Parameters
folder_id
required
string (Folder Id)

Unique identifier of a folder. - example: 12345

Responses

Response samples

Content type
application/json
{
  • "id": "12345",
  • "name": "XMAS Promotion",
  • "type": "QR_CODE",
  • "parent_id": "12345",
  • "has_subfolders": true,
  • "is_archived": false
}

Delete a folder

Deletes a folder.

Authorizations:
HTTPBearer
path Parameters
folder_id
required
string (Folder Id)

Unique identifier of a folder. - example: 12345

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Resets the statistics of a folder

Resets the QR Code statistics of all QR codes in a folder.

Authorizations:
HTTPBearer
path Parameters
folder_id
required
string (Folder Id)

Unique identifier of a folder. - example: 12345

Responses

Response samples

Content type
application/json
{
  • "detail": "Invalid authentication token"
}

Get the statistics of a folder

Get the folder statistics identified by its folder id.

Authorizations:
HTTPBearer
path Parameters
folder_id
required
string (Folder Id)

Unique identifier of a folder. - example: 12345

query Parameters
Country Code (string) or Country Code (null) (Country Code)

Filter by country code (exact match) - example: DE

Scan Date From (string) or Scan Date From (null) (Scan Date From)

Filter scans of QR codes in folder from this date (inclusive) - example: 2025-09-27

Scan Date To (string) or Scan Date To (null) (Scan Date To)

Filter scans of QR codes in folder up to this date (inclusive) - example: 2025-09-30

DateRelativeRange (string) or Scan Date Relative Range (null) (Scan Date Relative Range)

Filter scans of QR codes in the folder via a relative day range selector

SortOrder (string) or Sort Order (null) (Sort Order)

Sort the result by scan date ascending or descending

page
integer (Page) >= 1
Default: 1
size
integer (Size) [ 1 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "id": "12345",
  • "name": "XMAS Promotion",
  • "first_scan_at": "2025-09-15 15:22:09",
  • "last_scan_at": "2025-09-15 15:22:09",
  • "days_between_first_and_last_scan": 12,
  • "scan_count": 12,
  • "scan_count_per_day_first_last": 12.3
}

Default

Health

Responses

Response samples

Content type
application/json
null

This website uses necessary cookies to ensure that our website is ideally usable. We do not use cookies that process personal data without your prior consent. Read our Cookie Policy