Customization

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

Style a QR code with the optional styles, frameOptions and logoOptions objects when you create or update it. All fields are optional, and defaults apply to anything you leave out. The same three objects work on QR codes, templates and bulk creations. Unknown shapes, frames or logos are rejected with 422.

Example design object

{
  "styles": {
    "dotsOptions": { "type": "rounded", "color": "#000000" },
    "backgroundOptions": { "color": "#ffffff" },
    "cornersSquareOptions": { "type": "dot", "color": "#000000" },
    "cornersDotOptions": { "type": "dot", "color": "#000000" }
  },
  "frameOptions": { "id": "card", "text": "Scan me!", "color": "#000000", "textColor": "#ffffff" },
  "logoOptions": { "type": "suggested", "id": "logo-google", "scalePercent": 25 }
}

Send it with the rest of the QR code:

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" } },
    "frameOptions": { "id": "card", "text": "Scan me!" },
    "logoOptions": { "type": "suggested", "id": "logo-website-3" }
  }'

Styles

The styles object sets the pattern shapes and colors.

Field	Values
`dotsOptions.type`	Body dot shape: `square`, `dots`, `rounded`, `classy`, `classy-rounded`, `extra-rounded`
`cornersSquareOptions.type`	Corner-square (eye frame) shape: `square`, `rounded`, `dot`, `classy-rounded`
`cornersDotOptions.type`	Corner-dot (eye ball) shape: `square`, `dot`, `dots`, `rounded`, `classy`
`dotsOptions.color`	Foreground color. Default `#000000`.
`backgroundOptions.color`	Background color. Default `#ffffff`.
`cornersSquareOptions.color`, `cornersDotOptions.color`	Accepted but have no effect: corners always use `dotsOptions.color`.

Colors. Hex values only: #RGB or #RRGGBB.
Error correction. Always Q, and not an input. Sending styles.qrOptions gets 422.
Branded and AI designs. Can’t be set through the API. Sending styles.logoQrArt gets 422.
Content. styles.data is ignored. The image always encodes the QR code’s content.

Keep enough contrast between the foreground and background colors, with a dark foreground on a light background. Low-contrast codes may not scan. See Colors.

Frames

The frameOptions object adds a decorative frame with a call to action around the QR code.

Field	Description
`id`	Required when you send `frameOptions`. The frame type, from the lists below. `none` means no frame.
`text`	Call-to-action label, up to 12 characters. Default `Scan me!`.
`color`	Frame color, hex.
`textColor`	Label color, hex. Must differ from `color` when the frame shows a label, unless the pair is one of the frame’s built-in color presets.
`borderColor`	Border color, hex.
`fingerPrintColor`	Accent color of the frame icon, hex.

General frames

none, card, card-1, card-2, card-3, card-4, card-5, card-7, card-8, card-9, card-10, card-11, card-12, card-13, card-14, card-15, card-hor, wreath, envelope, waitress, coffee-cup, scooter, clipboardcard-hor shows no label.

Frames by QR code type

Type	Frames with a label	Frames without a label
App Link	`app-3`	`app-1`, `app-2`
vCard	`contact-1`, `contact-5`	`contact-2`, `contact-3`, `contact-4`
Email	`email-1`	`email-2`, `email-3`, `email-4`, `email-5`
Feedback	—	`feedback-1`, `feedback-2`, `feedback-3`, `feedback-4`, `feedback-5`
Image	—	`image-1`, `image-2`, `image-3`, `image-4`, `image-5`, `image-6`
Location	`location-3`	`location-1`, `location-2`, `location-4`, `location-5`, `location-6`
Multi-Link	`multilink-3`	`multilink-1`, `multilink-2`
Payment	—	`payment-1`, `payment-2`, `payment-3`, `payment-4`, `payment-5`
PDF	`pdf-1`	`pdf-2`, `pdf-3`, `pdf-4`
SMS	`sms-3`, `sms-5`, `sms-7`	`sms-1`, `sms-2`, `sms-4`, `sms-6`
Social Media	`social-3`	`social-1`, `social-2`, `social-4`
Video	`video-1`, `video-3`	`video-2`, `video-4`, `video-5`, `video-6`
Website	`website-1`	`website-2`, `website-3`, `website-4`, `website-5`
WhatsApp	`whatsapp-2`	`whatsapp-1`, `whatsapp-3`, `whatsapp-4`
WiFi	—	`wifi-1`, `wifi-2`, `wifi-3`, `wifi-4`

Any frame works with any QR code type. The grouping matches the dashboard.

Frames without a label have no call-to-action field in the dashboard, and the rule that textColor must differ from color doesn’t apply to them.

Logos

The logoOptions object places a logo in the center of the QR code. Set type to pick the kind of logo.

Suggested logo

Set type to suggested and pick an id from the catalog. Use logo-none for no logo.

{ "logoOptions": { "type": "suggested", "id": "logo-instagram", "scalePercent": 25 } }

All suggested logo IDs

logo-none, logo-website-3, logo-website-4, logo-link, logo-pdf-1, logo-pdf-2, logo-pdf-3, logo-picture-1, logo-picture-2, logo-picture-3, logo-picture-5, logo-picture-7, logo-picture-8, logo-video-1, logo-video-5, logo-whatsapp-1, logo-whatsapp-2, logo-whatsapp, logo-wifi-1, logo-wifi-2, logo-wifi-3, logo-wifi, logo-airbnb, logo-apple, logo-binance, logo-bitcoin, logo-bolt-food, logo-booking, logo-facebook, logo-glovo, logo-google, logo-google-maps, logo-google-play, logo-instagram, logo-linkedin, logo-location, logo-mail, logo-paypal, logo-stripe, logo-venmo, logo-cashapp, logo-braintree, logo-square, logo-verifone, logo-google-pay, logo-apple-pay, logo-klarna, logo-ayden, logo-giropay, logo-cartes-bancaires, logo-restaurant, logo-scan-me, logo-tripadvisor, logo-trustpilot, logo-uber-eats, logo-youtube, logo-spotify, logo-spotify-black

Your own logo

Upload the image

Reference the file

Set type to uploaded and fileId to the returned fileId. fileId is required, and it must be an ID returned by the Files endpoint.

{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }

An unknown file, an unfinished upload or a file uploaded for another target is rejected.

Logo size

scalePercent sets the logo size as a percentage of the QR code. It takes a whole number from 15 to 45. The default is 25. Other values, including ratios such as 0.25, get 422.

Updating a design

Partial updates. On Update a QR code, styles, frameOptions and logoOptions are merged into the stored design. A partial object changes only what it names.
Changing the logo. Picking another logo replaces the stored one but keeps its scalePercent.
Templates. With templateId on create, the fields you send are merged on top of the template’s design. See Templates.
Branded and AI designs. A QR code with designKind branded or ai was made in the dashboard. The API can’t edit its picture, but keeps it when you change other fields.
Reading a design. Responses return the stored design under design, in the same shape as the request fields, so you can send it back.

Common issues

422 "Error correction is always Q and is not an input"

Remove styles.qrOptions from the request.

422 "Frame caption is at most 12 characters"

Shorten frameOptions.text to 12 characters or fewer.

422 "Frame caption color must differ from the frame color"

textColor and color are the same on a frame that shows a label. Pick a contrasting textColor.

422 "Logo scale is a whole number from 15 to 45"

Send scalePercent as a whole percentage, for example 25, not 0.25.

The corner color doesn't change

Corners always use dotsOptions.color. cornersSquareOptions.color and cornersDotOptions.color have no effect.

API

Example design object

Styles

Frames

Logos

Suggested logo

Your own logo

Logo size

Updating a design

Common issues

What’s next

QR codes

Templates

Files

Design overview

​Example design object

​Styles

​Frames

​Logos

​Suggested logo

​Your own logo

​Logo size

​Updating a design

​Common issues

​What’s next

QR codes

Templates

Files

Design overview

Example design object

Styles

Frames

Logos

Suggested logo

Your own logo

Logo size

Updating a design

Common issues

What’s next