---
title: "Create a QR. Either supply `templateId` or `type` + per-type fields."
method: POST
path: "/api/v1/qrs"
tags: ["QR Codes"]
---

# Create a QR. Either supply \`templateId\` or \`type\` + per-type fields.

`POST /api/v1/qrs`

## Request

- Base URL: `https://qrlia.dev.castlesoft.eu`
- URL: `https://qrlia.dev.castlesoft.eu/api/v1/qrs`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `qrc_session`

## Request body

- union
  - object
    - `templateId` string, uuid, required
    - `label` string
    - `payload` object
    - `designId` string, uuid, nullable
    - `folderId` string, uuid, nullable
    - `companyId` string, uuid: Company to create the QR in. Company templates default to their own company.
  - union
    - object
      - `type` 'url', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `targetUrl` string, uri, required
      - `rules` object[]
        - `targetUrl` string, uri, required
        - `label` string
        - `countryIn` string[]
        - `deviceIn` string[]
        - `hourBetween` unknown[]
          - unknown
        - `dateAfter` string, date-time
        - `dateBefore` string, date-time
        - `languageIn` string[]
        - `osIn` string[]
        - `scansBelow` integer
    - object
      - `type` 'profile_card', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `profile` object, required
        - `displayName` string, required
        - `title` string
        - `organization` string
        - `tagline` string
        - `avatarUrl` string
        - `emails` string[]
        - `phones` object[]
          - `label` string, required
          - `number` string, required
          - `type` 'work' | 'cell' | 'home'
        - `website` string, uri
        - `address` object
          - `street` string
          - `city` string
          - `region` string
          - `postalCode` string
          - `country` string
        - `socials` object[]
          - `platform` 'linkedin' | 'x' | 'instagram' | 'facebook' | 'youtube' | 'github' | 'whatsapp' | 'tiktok' | 'threads' | 'other', required
          - `url` string, uri, required
          - `label` string
        - `note` string
    - object
      - `type` 'multilink', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `multilink` object, required
        - `title` string, required
        - `tagline` string
        - `avatarUrl` string, uri
        - `links` object[], required
          - `title` string, required
          - `url` string, uri, required
          - `description` string
          - `icon` string
    - object
      - `type` 'menu', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `menu` object, required
        - `title` string, required
        - `tagline` string
        - `currency` string
        - `sections` object[], required
          - `title` string, required
          - `description` string
          - `items` object[], required
            - `name` string, required
            - `description` string
            - `priceCents` integer
            - `currency` string
            - `imageUrl` string, uri
            - `tags` string[]
    - object
      - `type` 'feedback', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `feedback` object, required
        - `title` string, required
        - `tagline` string
        - `ratingLabel` string
        - `thankYou` string
        - `requireContact` boolean
        - `notifyEmail` string, email
        - `reviewUrl` string, uri
        - `reviewMinRating` integer
        - `reviewLabel` string
    - object
      - `type` 'pdf', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `pdf` object, required
        - `title` string
        - `description` string
        - `fileUrl` string, required
        - `filename` string
    - object
      - `type` 'image', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `image` object, required
        - `title` string
        - `caption` string
        - `fileUrl` string, required
        - `alt` string
    - object
      - `type` 'audio', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `audio` object, required
        - `title` string, required
        - `artist` string
        - `coverUrl` string
        - `fileUrl` string, required
    - object
      - `type` 'video', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `video` object, required
        - `title` string
        - `description` string
        - `posterUrl` string
        - `fileUrl` string, required
    - object
      - `type` 'app', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `app` object, required
        - `title` string
        - `tagline` string
        - `iosUrl` string, uri
        - `androidUrl` string, uri
        - `fallbackUrl` string, uri
        - `iconUrl` string
    - object
      - `type` 'dpp', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `dpp` object, required
        - `productName` string, required
        - `manufacturer` string, required
        - `gtin` string, required
        - `gs1DigitalLink` boolean
        - `batch` string
        - `serial` string
        - `countryOfOrigin` string
        - `materials` object[]
          - `name` string, required
          - `percentage` number
          - `origin` 'virgin' | 'recycled' | 'bio-based' | 'reused' | 'unknown'
        - `weightG` number
        - `recyclable` boolean
        - `recyclingInstructions` string
        - `endOfLife` string
        - `ceMarked` boolean
        - `hazards` string
        - `safetyDataSheetUrl` string, uri
        - `repairContactUrl` string, uri
        - `warrantyMonths` integer
        - `carbonFootprintKgCo2e` number
        - `sustainabilityScore` string
        - `specVersion` string
    - object
      - `type` 'coupon', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `coupon` object, required
        - `title` string, required
        - `offer` string, required
        - `code` string
        - `validUntil` string, date-time
        - `terms` string
        - `imageUrl` string
        - `ctaLabel` string
        - `ctaUrl` string, uri
    - object
      - `type` 'lead_form', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `leadForm` object, required
        - `title` string, required
        - `intro` string
        - `fields` object[], required
          - `key` string, required
          - `label` string, required
          - `type` 'text' | 'email' | 'phone' | 'textarea' | 'select' | 'checkbox', required
          - `required` boolean
          - `options` string[]
        - `consentText` string, required
        - `submitLabel` string
        - `thankYou` string
        - `redirectUrl` string, uri
    - object
      - `type` 'text' | 'email' | 'phone' | 'sms' | 'whatsapp' | 'wifi' | 'vcard' | 'event' | 'sepa' | 'paypal' | 'crypto', required
      - `label` string, required
      - `designId` string, uuid, nullable: Saved design (designs_list) to render this QR with.
      - `folderId` string, uuid, nullable: Folder to file the QR in; null = company root. Plan feature qr_folders.
      - `companyId` string, uuid: Company to create the QR in. Defaults to your pinned/active company, else the workspace's default company.
      - `access` object: Password, start date, expiry date or scan limit.
        - `password` string, nullable: Visitors must enter it before the code opens.
        - `startsAt` string, date-time, nullable: Code shows a 'not active yet' message (or fallbackUrl) before this time.
        - `expiresAt` string, date-time, nullable: After this time the code shows its expiry message (or fallbackUrl).
        - `maxScans` integer, nullable: Stop after this many scans by people (bots don't count).
        - `fallbackUrl` string, uri, nullable: Where not-started / expired / used-up codes send visitors.
        - `fallbackMessage` string, nullable
      - `tracking` object: Analytics tags and opt-in location for the landing page; URL codes show a short consent page first.
        - `ga4Id` string, nullable
        - `metaPixelId` string, nullable
        - `gtmId` string, nullable
        - `requestLocation` boolean, nullable: Ask visitors (opt-in) to share an approximate location (~1 km).
      - `payload` object

## Response `201`

Created

- Qr
  - `id` string, uuid, required
  - `tenantId` string, uuid, required
  - `companyId` string, uuid, required
  - `type` 'url' | 'vcard' | 'profile_card' | 'text' | 'email' | 'phone' | 'sms' | 'whatsapp' | 'wifi' | 'pdf' | 'image' | 'audio' | 'video' | 'app' | 'multilink' | 'menu' | 'feedback' | 'event' | 'dpp' | 'coupon' | 'sepa' | 'paypal' | 'crypto' | 'lead_form', required: Discriminator for QR payload shape.
  - `slug` string, nullable, required
  - `label` string, required
  - `payload` object, required
  - `designId` string, uuid, nullable, required
  - `folderId` string, uuid, nullable, required
  - `status` 'active' | 'paused' | 'archived', required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `shortLink` string, uri, nullable: The link the printed code encodes (https://<host>/r/<slug>).
  - `access` object
    - `passwordProtected` boolean, required
    - `startsAt` string, nullable, required
    - `expiresAt` string, nullable, required
    - `maxScans` number, nullable, required
    - `fallbackUrl` string, nullable, required
    - `fallbackMessage` string, nullable, required
  - `tracking` object
    - `ga4Id` string
    - `metaPixelId` string
    - `gtmId` string
    - `requestLocation` boolean
  - `totalScans` integer: All-time scans; included by list and get.

## Other responses

- `400`: Validation failed
- `401`: Authentication required
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict
- `500`: Internal

---

[API](https://skmtc.dev/qrlia/apis/qrlia-api.md) · [All operations](https://skmtc.dev/qrlia/apis/qrlia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qrlia/apis/qrlia-api/revisions/01c5dd6002ab?raw)