Create QR Code

POST

qr-codes

curl --request POST \
  --url https://api.useqrkit.com/v1/qr-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "gs1",
  "mode": "dynamic",
  "name": "Cocoa 200g",
  "primary_key": {
    "ai": "01",
    "value": "09506000134352"
  },
  "qualifiers": [
    {
      "ai": "10",
      "value": "LOT1"
    }
  ],
  "attributes": {
    "17": "270601"
  },
  "destination": "https://brand.example/products/cocoa-200g",
  "links": [
    {
      "linkType": "gs1:pip",
      "href": "https://brand.example/products/cocoa-200g",
      "title": "Product information",
      "hreflang": [
        "en"
      ]
    },
    {
      "linkType": "gs1:instructions",
      "href": "https://brand.example/products/cocoa-200g/how-to",
      "title": "How to use"
    }
  ],
  "overrides": [
    {
      "path": "10/LOT1",
      "href": "https://brand.example/recalls/2026-07"
    }
  ]
}
'

{
  "id": "qr_123",
  "object": "qr_code",
  "kind": "dynamic",
  "name": "<string>",
  "type": "url",
  "short_code": "AB3D5",
  "short_url": "https://qrkit.to/AB3D5",
  "domain_id": "dom_3",
  "gs1": {
    "mode": "static",
    "key": "01/09506000134352/10/LOT1",
    "digital_link": "<string>",
    "primary_key": {
      "ai": "<string>",
      "value": "<string>"
    },
    "qualifiers": [
      {
        "ai": "<string>",
        "value": "<string>"
      }
    ],
    "attributes": {},
    "links": [
      {
        "linkType": "gs1:pip",
        "href": "<string>",
        "title": "<string>",
        "hreflang": [
          "<string>"
        ],
        "type": "<string>",
        "context": [
          "<string>"
        ]
      }
    ],
    "overrides": [
      {
        "path": "10/LOT1",
        "href": "<string>",
        "links": [
          {
            "linkType": "gs1:pip",
            "href": "<string>",
            "title": "<string>",
            "hreflang": [
              "<string>"
            ],
            "type": "<string>",
            "context": [
              "<string>"
            ]
          }
        ]
      }
    ],
    "linkset_url": "https://api.useqrkit.com/v1/qr-codes/qr_123/linkset"
  },
  "target": {
    "type": "<string>",
    "destination": "<string>",
    "editable": true,
    "summary": {
      "title": "<string>",
      "menus": 123,
      "items": 123
    }
  },
  "design": {
    "colors": {
      "foreground": "<string>",
      "background": "<string>"
    },
    "gradient": {
      "start": "<string>",
      "end": "<string>",
      "type": "<string>"
    },
    "shapes": {
      "body": "<string>",
      "eye_frame": "<string>",
      "eye_ball": "<string>"
    },
    "eye_colors": {
      "frame": "<string>",
      "ball": "<string>"
    },
    "has_logo": true,
    "transparent_background": true
  },
  "folder_id": "fld_12",
  "tags": [
    "<string>"
  ],
  "image_url": "https://img.useqrkit.com/qr-AB3D5-1717000000000.svg",
  "download_url": "/v1/qr-codes/qr_123/download",
  "is_active": true,
  "scan_count": 123,
  "utm": {
    "source": "<string>",
    "medium": "<string>",
    "campaign": "<string>",
    "term": "<string>",
    "content": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "deleted_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

API key in the Authorization header: Bearer qr_live_… or Bearer qr_test_…. Token endpoints take a Clerk session JWT instead.

Body

application/json

Option 1
Option 2

target

object

required

What the QR code points to. Each type takes structured fields; the link types and most static types also accept a pre-encoded destination string if you prefer to encode yourself.

type	Fields	Static / dynamic
`url`	`destination`, optional `utm`	Your choice, dynamic by default
`youtube`, `instagram`, `facebook`, `tiktok`, `x`, `pinterest`, `linktree`, `googleform`	`destination` (http/https)	Your choice, dynamic by default. Shown in the dashboard with the platform's label and icon
`whatsapp`	`phone` (international format, no leading 0) + optional `message` (max 500), or a wa.me / chat.whatsapp.com link in `destination`	Your choice, dynamic by default
`telegram`	`destination`: a `@username`, an international phone number, or a t.me link	Your choice, dynamic by default
`location`	`lat`, `lng`, optional `label`, `address`, `map_app`	Your choice, dynamic by default. A static code is a fixed Google Maps link; a dynamic code opens the app set in `map_app` (`auto`: Apple Maps on iPhone/iPad, Google Maps elsewhere)
`appstores`	one or more of `ios_url`, `android_url`, `harmony_url`	Always dynamic: a hosted page sends each phone to its own store. Edit its links in the dashboard
`review`	`review_page`	Always dynamic: a hosted page with one button per review site. Returned as `type: "linkpage"`; edit its content in the dashboard's Link Page editor (`PATCH target` is refused)
`text`, `email`, `sms`, `wifi`, `event`	see fields below	Static by default; pass `type: "dynamic"` for a hosted page
`vcard`	`vcard`	Always dynamic

Show child attributes

name

string

Defaults to "Campaign {code}" / "Static {code}".

Maximum string length: 255

type

enum<string>

Chooses the mode where the type allows it. url defaults to dynamic; wifi/text/email/sms/event default to static but accept dynamic (hosted scan page, editable, scan analytics — requires structured target fields, not a pre-encoded destination); vcard, appstores and review always dynamic; url, the link types (youtube … googleform), whatsapp, telegram and location default to dynamic and accept static. Omit to use the type's default.

Available options:

dynamic,

static

design

object

Visual customization. Stored with the code, so the dashboard shows exactly what the API created.

Show child attributes

folder_id

string

Folder to place the code in (e.g. fld_12).

domain_id

string | null

Dynamic codes only: the scan host printed in the QR. Omit it to use the workspace's primary custom domain when it has an active one and the plan includes custom domains (Plus and up) — the same default the dashboard uses — pass null for the default QRKit host, or a dom_<n> id from GET /v1/me → custom_domains. An id that is not an active custom domain of the workspace is refused (422), as is any non-null domain_id on a static code; naming a domain on a plan without custom domains is 403. In a batch, every item's domain is checked before the batch is accepted. The host is fixed once the code exists: PATCH refuses a different domain_id (sending the current value is accepted, except on GS1 codes, which refuse any domain_id). GS1 codes use their own domain_id (see CreateGs1QrCodeRequest).

Example:

"dom_3"

Response

QR code created

string

qr_… for dynamic, sqr_… for static.

Example:

"qr_123"

object

string

Example:

"qr_code"

kind

enum<string>

Available options:

dynamic,

static

name

string

type

string

The stored type: any target.type the API creates (a review is stored as linkpage), gs1, or a dashboard-only type such as file, menupage, form or smarturl. Treat unknown values as opaque.

Example:

"url"

short_code

string

Example:

"AB3D5"

short_url

string | null

null for static codes. On the workspace custom domain when the code was created on one. For a dynamic GS1 code this is the Digital Link URI itself, not <host>/<short_code>.

Example:

"https://qrkit.to/AB3D5"

domain_id

string | null

The custom domain short_url is on, or null for the default host (and for static codes).

Example:

"dom_3"

gs1

object

Present on GS1 codes only. The identifier half is READ-ONLY (R4 — it is printed); links and overrides are the editable half.

Show child attributes

target

object

Show child attributes

design

object | null

Show child attributes

folder_id

string | null

Example:

"fld_12"

tags

string[]

image_url

string

Example:

"https://img.useqrkit.com/qr-AB3D5-1717000000000.svg"

download_url

string

Example:

"/v1/qr-codes/qr_123/download"

is_active

boolean

Dynamic codes: whether the redirect is on. Static codes: false while the code is in the Trash (the printed payload itself keeps working).

scan_count

integer | null

null for static codes (no tracking).

utm

object | null

UTM parameters (null unless set on a dynamic url code).

Show child attributes

created_at

string<date-time>

updated_at

string<date-time>

deleted_at

string<date-time> | null

null for a live code. Set while the code is in the Trash (or paused by a plan downgrade); restore it with POST /v1/qr-codes/{id}/restore.

curl --request POST \
  --url https://api.useqrkit.com/v1/qr-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "gs1",
  "mode": "dynamic",
  "name": "Cocoa 200g",
  "primary_key": {
    "ai": "01",
    "value": "09506000134352"
  },
  "qualifiers": [
    {
      "ai": "10",
      "value": "LOT1"
    }
  ],
  "attributes": {
    "17": "270601"
  },
  "destination": "https://brand.example/products/cocoa-200g",
  "links": [
    {
      "linkType": "gs1:pip",
      "href": "https://brand.example/products/cocoa-200g",
      "title": "Product information",
      "hreflang": [
        "en"
      ]
    },
    {
      "linkType": "gs1:instructions",
      "href": "https://brand.example/products/cocoa-200g/how-to",
      "title": "How to use"
    }
  ],
  "overrides": [
    {
      "path": "10/LOT1",
      "href": "https://brand.example/recalls/2026-07"
    }
  ]
}
'

{
  "id": "qr_123",
  "object": "qr_code",
  "kind": "dynamic",
  "name": "<string>",
  "type": "url",
  "short_code": "AB3D5",
  "short_url": "https://qrkit.to/AB3D5",
  "domain_id": "dom_3",
  "gs1": {
    "mode": "static",
    "key": "01/09506000134352/10/LOT1",
    "digital_link": "<string>",
    "primary_key": {
      "ai": "<string>",
      "value": "<string>"
    },
    "qualifiers": [
      {
        "ai": "<string>",
        "value": "<string>"
      }
    ],
    "attributes": {},
    "links": [
      {
        "linkType": "gs1:pip",
        "href": "<string>",
        "title": "<string>",
        "hreflang": [
          "<string>"
        ],
        "type": "<string>",
        "context": [
          "<string>"
        ]
      }
    ],
    "overrides": [
      {
        "path": "10/LOT1",
        "href": "<string>",
        "links": [
          {
            "linkType": "gs1:pip",
            "href": "<string>",
            "title": "<string>",
            "hreflang": [
              "<string>"
            ],
            "type": "<string>",
            "context": [
              "<string>"
            ]
          }
        ]
      }
    ],
    "linkset_url": "https://api.useqrkit.com/v1/qr-codes/qr_123/linkset"
  },
  "target": {
    "type": "<string>",
    "destination": "<string>",
    "editable": true,
    "summary": {
      "title": "<string>",
      "menus": 123,
      "items": 123
    }
  },
  "design": {
    "colors": {
      "foreground": "<string>",
      "background": "<string>"
    },
    "gradient": {
      "start": "<string>",
      "end": "<string>",
      "type": "<string>"
    },
    "shapes": {
      "body": "<string>",
      "eye_frame": "<string>",
      "eye_ball": "<string>"
    },
    "eye_colors": {
      "frame": "<string>",
      "ball": "<string>"
    },
    "has_logo": true,
    "transparent_background": true
  },
  "folder_id": "fld_12",
  "tags": [
    "<string>"
  ],
  "image_url": "https://img.useqrkit.com/qr-AB3D5-1717000000000.svg",
  "download_url": "/v1/qr-codes/qr_123/download",
  "is_active": true,
  "scan_count": 123,
  "utm": {
    "source": "<string>",
    "medium": "<string>",
    "campaign": "<string>",
    "term": "<string>",
    "content": "<string>"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "deleted_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "reason": "NOT_IN_TRASH",
    "gs1_code": "NOT_ENTITLED",
    "field": "<string>",
    "fields": [
      "<string>"
    ],
    "limit": 123,
    "current_count": 123,
    "requested": 123,
    "plan_id": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

Overview

Account

QR Codes

Batches

Folders

Tokens

Account

QR Codes

Batches

Folders

Tokens

Webhooks

Events

Authorizations

Body

Response