> ## Documentation Index
> Fetch the complete documentation index at: https://shortpen.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create QR Code

> Creates a QR code with the styles of the QR designer: the QR of a new short link, of an uploaded PDF, or a static one. Plan limits (QR codes and links per month, paid styles) apply as in the dashboard.

Create a QR code with every style of the QR designer: the QR of a new short link, the QR of a PDF, or a static QR code (Text, Wi-Fi, vCard and more). The same plan limits as the dashboard apply: QR codes and links per month, and paid styles.

> [!TIP]
>
> Need only a plain link with a basic QR? [`POST /v1/generate`](./generate) still works, and its `qr_template_id` applies one of your QR templates to the link's QR.

### Types

| `type` | What it creates | Required fields |
| - | - | - |
| `link` | A short link and its QR code. Scans are tracked like any link. | `url`, `domain_id` |
| `pdf` | A short link that downloads the PDF you send. Password protection works as for links: the password is asked before the download. | `pdf_data`, `domain_id` |
| `text`, `wifi`, `vcard`, `mecard`, `location`, `bitcoin`, `email`, `phone`, `sms`, `whatsapp` | A static QR code: the content is inside the code, there is no link and no redirect. | `content` |

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | string | ✅ | One of the types above. |
| `content` | object | static types | Fields of the static type, see [Content fields](#content-fields). |
| `url` | string | `link` | Destination URL. |
| `domain_id` | integer | `link`, `pdf` | Domain of the short link. Use [`POST /v1/get`](./get-resources) with `resource: "domain"`. |
| `pdf_data` | base64 string | `pdf` | The PDF file. A `data:application/pdf;base64,` prefix is accepted. 20 MB at most. |
| `pdf_name` | string | | File name of the download. Defaults to `document.pdf`. |
| `design` | object | | Styles of the code, see [Design](#design). Send only what you want to change. |
| `logo` | enum(`none`, `organization`, `upload`) | | Logo in the center: none, your organization logo, or the image in `logo_data`. |
| `logo_data` | base64 string | | PNG, JPEG or SVG image, 2 MB at most. Sending it implies `logo: "upload"`. |
| `qr_template_id` | integer | | One of your QR templates as the starting design and logo. `design` and `logo` override it. Leave it out to start from the workspace's default template (if one is set), or send `null` for no template. Paid plans only. |
| `workspace_id` | integer | | Workspace of the QR code. Defaults to the first workspace of the organization. |
| `title` | string | | `link` and `pdf`: title in your lists. A PDF without one gets the file name. Static types get a title from their content. |
| `notes` | string | | Private note, 300 characters max. |
| `custom_slug`, `folder_id`, `tag_ids`, `redirect_type`, `with_password`, `url_password` | | | `link` and `pdf`: same as in [Create Link](https://shortpen.com/docs/api-reference/endpoint/generate.md). `param` works for `link`. |

### Content fields

| `type` | Fields (required in bold) |
| - | - |
| `text` | **`text`** (500) |
| `wifi` | **`ssid`**, `password` (required unless `encryption` is `nopass`), `encryption` (`WPA`, `WEP`, `nopass`; default `WPA`), `hidden` (boolean) |
| `vcard` | **`first_name`**, `last_name`, `organization`, `title`, `email`, `phone`, `url` |
| `mecard` | **`first_name`**, `last_name`, `phone`, `email`, `url`, `address` |
| `location` | **`latitude`** (-90 to 90), **`longitude`** (-180 to 180) |
| `bitcoin` | **`address`**, `amount` (greater than 0), `label` |
| `email` | **`to`**, `subject`, `body` |
| `phone` | **`number`** |
| `sms` | **`number`**, `body` |
| `whatsapp` | **`number`** (with the country code), `body` |

Emails must be valid addresses, websites must start with `http://` or `https://`, and longer values are cut to the field's length.

### Design

Every key is optional. What you leave out comes from `qr_template_id` if you send one, otherwise from the workspace's default template if one is set, otherwise from the defaults below.

| Key | Values | Free plan |
| - | - | - |
| `module_style` | `square` (default), `dots`, `smooth`, `extra-rounded`, `vertical`, `gapped`, `classy`, `diamond`, `chamfer` | `square`, `dots` |
| `eye_frame_style` | `square` (default), `circle`, `rounded`, `drop`, `leaf`, `pointed`, `soft` | `square`, `circle` |
| `eye_ball_style` | `square` (default), `circle`, `rounded`, `drop`, `leaf`, `star`, `diamond`, `sunburst`, `sparkle`, `octagon` | `square`, `circle` |
| `frame_layout` | `none` (default), `box` (bottom label), `box-top` (top label), `banner-bottom`, `banner-top`, `balloon` | `none`, `box` |
| `frame_text` | Text of the frame, 24 characters max | all |
| `foreground_color` | Hex color, default `#000000` | all |
| `background_color` | Hex color or `transparent`, default `#FFFFFF` | all |
| `eye_frame_color`, `eye_ball_color` | Hex color or `match` (follows `foreground_color`, the default) | all |
| `frame_color`, `frame_text_color` | Hex colors, defaults `#000000` and `#FFFFFF` | all |

> [!NOTE]
>
> On a Free plan a paid style gets a `403` whose `data.paid_options` lists the keys to change. Pick a free value, or upgrade your plan.

### Response

* `data.id`: ID of the QR code. Use it as `url_id` with [Edit QR Code](https://shortpen.com/docs/api-reference/endpoint/edit-qr.md).
* `data.type`: the type you created.
* `data.link`: the short link for `link` and `pdf`, `null` for static types.
* `data.qr`: the QR code as a PNG data URI, 1024 px wide.
* `data.created`: `true`.

### Errors

Every error has the standard envelope, and `message` says what to fix.

| Status | When |
| - | - |
| `403` | A paid style or a QR template on a Free plan, or phone verification required. |
| `404` | The QR template is not in your organization. |
| `409` | The custom slug is already taken. |
| `422` | A missing or invalid field (`data.errors` lists them), incomplete content, an unknown design key or value, a file that is not a PDF or an image. |
| `429` | Monthly QR code or link limit reached. |


## OpenAPI

````yaml POST /v1/qr
openapi: 3.1.0
info:
  title: ShortPen API
  version: 1.0.0
  description: >-
    Create branded links, fetch organization resources, and pull analytics
    programmatically with the ShortPen REST API.
servers:
  - url: https://{environment}.shortpen.com
    description: ShortPen API host
    variables:
      environment:
        default: api
        enum:
          - api
          - staging-api
security: []
tags:
  - name: Core
    description: Utility endpoints for checking service health.
  - name: Authentication
    description: Endpoints that return identity, limits, and feature availability.
  - name: Links
    description: Create, edit, and list links and their auxiliary assets like QR codes.
  - name: QR Codes
    description: >-
      Create and edit QR codes: the QR of a short link, of a PDF, or a static
      one (Text, Wi-Fi, vCard...), with every style of the QR designer.
  - name: Resources
    description: >-
      Lookup supporting entities such as domains, workspaces, folders, and
      pixels.
  - name: Analytics
    description: Retrieve click analytics and raw tracking events.
paths:
  /v1/qr:
    post:
      tags:
        - QR Codes
      summary: Create a QR code
      description: >-
        Creates a QR code with the styles of the QR designer: the QR of a new
        short link, of an uploaded PDF, or a static one. Plan limits (QR codes
        and links per month, paid styles) apply as in the dashboard.
      operationId: createQr
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQrRequest'
            examples:
              link:
                summary: Link QR with a custom design
                value:
                  type: link
                  url: https://example.com/menu
                  domain_id: 1
                  title: Restaurant menu
                  design:
                    module_style: dots
                    eye_frame_style: rounded
                    foreground_color: '#1F4E79'
                    frame_layout: box
                    frame_text: SCAN ME
                  logo: organization
              wifi:
                summary: Static Wi-Fi QR
                value:
                  type: wifi
                  content:
                    ssid: Office
                    password: s3cret-pass
                    encryption: WPA
                  design:
                    module_style: smooth
              pdf:
                summary: PDF QR
                value:
                  type: pdf
                  domain_id: 1
                  pdf_name: Menu.pdf
                  pdf_data: JVBERi0xLjQKJ...
              template:
                summary: vCard QR from a template
                value:
                  type: vcard
                  content:
                    first_name: Ada
                    last_name: Lovelace
                    email: ada@example.com
                  qr_template_id: 7
      responses:
        '200':
          description: QR code created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QrResponse'
        '400':
          description: Nothing to change (edit only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            A paid option or a QR template on a Free plan (`data.paid_options`
            lists the design keys), or phone verification required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: QR code or QR template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The custom slug is already taken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Validation error: `message` says what to fix, `data.errors` lists
            the fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Monthly QR code or link limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error, retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateQrRequest:
      type: object
      properties:
        type:
          type: string
          enum:
            - link
            - pdf
            - text
            - wifi
            - vcard
            - mecard
            - location
            - bitcoin
            - email
            - phone
            - sms
            - whatsapp
          description: >-
            `link`: a short link and its QR code. `pdf`: a short link that
            downloads the PDF in `pdf_data`. The others: a static QR code that
            holds `content` (no link, no redirect).
          example: link
        content:
          $ref: '#/components/schemas/QrContent'
        url:
          type: string
          maxLength: 2048
          description: '`link` only: destination URL. Required on creation.'
          example: https://example.com/menu
        domain_id:
          type: integer
          description: >-
            `link` and `pdf`: domain that hosts the short link. Required on
            creation.
          example: 1
        pdf_data:
          type: string
          description: >-
            `pdf` only: the PDF file, base64-encoded (a
            `data:application/pdf;base64,` prefix is accepted). 20 MB at most.
            Required on creation; on edit it replaces the file.
        pdf_name:
          type: string
          maxLength: 200
          description: >-
            `pdf` only: file name used for the download, with `pdf_data`.
            Defaults to `document.pdf`.
          example: Menu.pdf
        design:
          $ref: '#/components/schemas/QrDesign'
        logo:
          type: string
          enum:
            - none
            - organization
            - upload
          description: >-
            Logo in the center of the code: none, the organization logo, or the
            image in `logo_data`. Omitted: the template's logo, else the QR's
            current one (edit), else none.
        logo_data:
          type: string
          description: >-
            PNG, JPEG or SVG image, base64-encoded (a data URI is accepted), 2
            MB at most. Sending it implies `logo: "upload"`.
        qr_template_id:
          type: integer
          description: >-
            QR template of the organization used as the starting design and
            logo; `design` and `logo` override it. Left out, the workspace's
            default template is used if one is set; `null` means no template.
            Paid plans only.
          example: 7
        workspace_id:
          type: integer
          description: >-
            Workspace of a new QR code. Defaults to the first workspace of the
            organization. An edit never moves a QR code.
        title:
          type: string
          maxLength: 256
          description: >-
            `link` and `pdf`: title in your lists. A PDF without one gets the
            file name. Static types get a title from their content.
        notes:
          type: string
          maxLength: 300
          description: Private note.
        custom_slug:
          type: string
          maxLength: 64
          description: '`link` and `pdf`: branded slug instead of an auto-generated code.'
        folder_id:
          type: integer
          description: '`link` and `pdf`: folder of the link.'
        tag_ids:
          type: array
          items:
            type: integer
          description: >-
            `link` and `pdf`: tags of the link (same rules as the link
            endpoints).
        param:
          type: object
          additionalProperties:
            type: string
          description: >-
            `link` only: query parameters added to the destination URL (for
            example UTM tags).
        redirect_type:
          type: integer
          enum:
            - 301
            - 302
          description: '`link` and `pdf`: redirect status.'
        with_password:
          type: boolean
          description: '`link` and `pdf`: protects the link with `url_password`.'
        url_password:
          type: string
          description: Password asked before the redirect (or the download).
      required:
        - type
    QrResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status_code:
          type: integer
          example: 200
        message:
          type: string
          example: ''
        data:
          $ref: '#/components/schemas/QrData'
      required:
        - success
        - status_code
        - data
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status_code:
          type: integer
          example: 401
        message:
          type: string
          example: There was an error while processing your request.
        data:
          description: Optional payload returned for additional context.
          nullable: true
      required:
        - success
        - status_code
        - message
    QrContent:
      description: >-
        Fields of a static QR code, by `type`. Required on creation; on edit
        send only the fields to change.
      oneOf:
        - type: object
          title: text
          properties:
            text:
              type: string
              maxLength: 500
              description: Any text.
          required:
            - text
          example:
            text: Welcome to the office!
        - type: object
          title: wifi
          properties:
            ssid:
              type: string
              maxLength: 32
              description: Network name.
            password:
              type: string
              maxLength: 63
              description: Required unless `encryption` is `nopass`.
            encryption:
              type: string
              enum:
                - WPA
                - WEP
                - nopass
              default: WPA
            hidden:
              type: boolean
              description: Hidden network.
          required:
            - ssid
          example:
            ssid: Office
            password: s3cret-pass
            encryption: WPA
        - type: object
          title: vcard
          properties:
            first_name:
              type: string
              maxLength: 64
              description: First name.
            last_name:
              type: string
              maxLength: 64
              description: Last name.
            organization:
              type: string
              maxLength: 100
              description: Company.
            title:
              type: string
              maxLength: 100
              description: Job title.
            email:
              type: string
              maxLength: 254
              description: A valid email address.
            phone:
              type: string
              maxLength: 32
              description: Phone number.
            url:
              type: string
              maxLength: 2048
              description: Website, starting with http:// or https://.
          required:
            - first_name
          example:
            first_name: Ada
            last_name: Lovelace
            email: ada@example.com
        - type: object
          title: mecard
          properties:
            first_name:
              type: string
              maxLength: 64
              description: First name.
            last_name:
              type: string
              maxLength: 64
              description: Last name.
            phone:
              type: string
              maxLength: 32
              description: Phone number.
            email:
              type: string
              maxLength: 254
              description: A valid email address.
            url:
              type: string
              maxLength: 2048
              description: Website, starting with http:// or https://.
            address:
              type: string
              maxLength: 200
              description: Postal address.
          required:
            - first_name
          example:
            first_name: Ada
            phone: +44 20 7946 0000
        - type: object
          title: location
          properties:
            latitude:
              type: string
              maxLength: 20
              description: Between -90 and 90. A decimal comma is read as a dot.
            longitude:
              type: string
              maxLength: 20
              description: Between -180 and 180.
          required:
            - latitude
            - longitude
          example:
            latitude: '45.4642'
            longitude: '9.1900'
        - type: object
          title: bitcoin
          properties:
            address:
              type: string
              maxLength: 100
              description: Wallet address.
            amount:
              type: string
              maxLength: 20
              description: Amount in BTC, greater than 0.
            label:
              type: string
              maxLength: 64
              description: Label shown by the wallet.
          required:
            - address
          example:
            address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
            amount: '0.001'
        - type: object
          title: email
          properties:
            to:
              type: string
              maxLength: 254
              description: A valid email address.
            subject:
              type: string
              maxLength: 120
              description: Subject.
            body:
              type: string
              maxLength: 500
              description: Message.
          required:
            - to
          example:
            to: hello@example.com
            subject: Hello
        - type: object
          title: phone
          properties:
            number:
              type: string
              maxLength: 32
              description: Phone number.
          required:
            - number
          example:
            number: +39 02 1234567
        - type: object
          title: sms
          properties:
            number:
              type: string
              maxLength: 32
              description: Phone number.
            body:
              type: string
              maxLength: 160
              description: Message.
          required:
            - number
          example:
            number: +39 333 1234567
            body: Hi!
        - type: object
          title: whatsapp
          properties:
            number:
              type: string
              maxLength: 32
              description: Phone number with the country code.
            body:
              type: string
              maxLength: 500
              description: Message.
          required:
            - number
          example:
            number: +39 333 1234567
            body: Hi!
    QrDesign:
      type: object
      description: >-
        Styles of the QR code, as in the QR designer. Send only what you want to
        change: the rest comes from `qr_template_id`, else from the QR being
        edited, else from the defaults. On a Free plan only the first two values
        of `module_style`, `eye_frame_style` and `eye_ball_style`, and `none` or
        `box` for `frame_layout`, can be saved.
      additionalProperties: false
      properties:
        module_style:
          type: string
          enum:
            - square
            - dots
            - smooth
            - extra-rounded
            - vertical
            - gapped
            - classy
            - diamond
            - chamfer
          default: square
          description: 'Pattern of the modules. Free: `square`, `dots`.'
        eye_frame_style:
          type: string
          enum:
            - square
            - circle
            - rounded
            - drop
            - leaf
            - pointed
            - soft
          default: square
          description: 'Outer frame of the three corner eyes. Free: `square`, `circle`.'
        eye_ball_style:
          type: string
          enum:
            - square
            - circle
            - rounded
            - drop
            - leaf
            - star
            - diamond
            - sunburst
            - sparkle
            - octagon
          default: square
          description: 'Center of the three corner eyes. Free: `square`, `circle`.'
        frame_layout:
          type: string
          enum:
            - none
            - box
            - box-top
            - banner-bottom
            - banner-top
            - balloon
          default: none
          description: >-
            Frame with a call to action around the code: `box` is a bottom
            label, `box-top` a top label. Free: `none`, `box`.
        frame_text:
          type: string
          maxLength: 24
          default: ''
          description: Text of the frame. HTML is removed, longer text is cut.
        foreground_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          default: '#000000'
          description: Color of the modules.
        background_color:
          type: string
          default: '#FFFFFF'
          description: Background color, or `transparent`.
        eye_frame_color:
          type: string
          default: match
          description: Color of the eye frames, or `match` to follow `foreground_color`.
        eye_ball_color:
          type: string
          default: match
          description: Color of the eye centers, or `match` to follow `foreground_color`.
        frame_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          default: '#000000'
          description: Color of the frame.
        frame_text_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          default: '#FFFFFF'
          description: Color of the frame text.
      example:
        module_style: dots
        eye_frame_style: rounded
        foreground_color: '#1F4E79'
        frame_layout: box
        frame_text: SCAN ME
    QrData:
      type: object
      properties:
        id:
          type: integer
          description: ID of the QR code, the `url_id` of the edit endpoint.
          example: 9012
        type:
          type: string
          enum:
            - link
            - pdf
            - text
            - wifi
            - vcard
            - mecard
            - location
            - bitcoin
            - email
            - phone
            - sms
            - whatsapp
          example: link
        link:
          type:
            - string
            - 'null'
          description: The short link (`link`, `pdf`); `null` for static types.
          example: https://shr.pn/a1B2
        qr:
          type: string
          description: The QR code as a PNG data URI (1024 px wide).
          example: data:image/png;base64,iVBORw0KGgo...
        created:
          type: boolean
          description: '`true` on creation, `false` on edit.'
      required:
        - id
        - type
        - link
        - qr
        - created
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Personal Access Token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.