Docs • Twilee

The QrCode resource exposes everything you need to create, manage, and distribute QR codes through Twilee. This guide walks thr ough each available operation, the data structures you will interact with, and examples that reflect the actual API responses.

Resource Representation

Responses expose a structured document that separates identifying data, appearance options, hosted attributes, and analytics. A real-world payload looks like this:

{
  "id": "68ef5bc4e581e7223e010b2e",
  "name": "Event test API",
  "type": "event",
  "content": {
    "name": "Test event",
    "eventType": "Test",
    "location": "Paris",
    "description": "lorem ipsum",
    "hostedPageBackgroundColor": "#f9fAfb",
    "hostedPagePrimaryColor": "#0ea5e9"
  },
  "metadata": {
    "shortToken": "frnKYa3c",
    "createdAt": "2025-10-15T08:31:00+00:00",
    "updatedAt": "2025-10-15T08:31:00+00:00"
  },
  "appearance": {
    "shape": "square",
    "predefinedImage": null,
    "uploadedImage": null,
    "margin": 10,
    "qrOptionsTypeNumber": 0,
    "qrOptionsMode": "Byte",
    "qrOptionsErrorCorrectionLevel": "Q",
    "imageOptionsHideBackgroundDots": true,
    "imageOptionsImageSize": 0.4,
    "imageOptionsMargin": 0,
    "dotsOptionsColor": "#0f172a",
    "dotsOptionsType": "extra-rounded",
    "dotsOptionsRoundSize": true,
    "dotsOptionsGradientType": null,
    "dotsOptionsGradientRotation": null,
    "dotsOptionsGradientColorStops": null,
    "backgroundOptionsColor": "#ffffff",
    "backgroundOptionsGradientType": null,
    "backgroundOptionsGradientRotation": null,
    "backgroundOptionsGradientColorStops": null,
    "cornersSquareOptionsColor": "#0f172a",
    "cornersSquareOptionsType": "extra-rounded",
    "cornersSquareOptionsGradientType": null,
    "cornersSquareOptionsGradientRotation": null,
    "cornersSquareOptionsGradientColorStops": null,
    "cornersDotOptionsColor": "#0f172a",
    "cornersDotOptionsType": "dot",
    "cornersDotOptionsGradientType": null,
    "cornersDotOptionsGradientRotation": null,
    "cornersDotOptionsGradientColorStops": null
  },
  "attributes": {
    "dynamicUrl": "https://qr-click-me.local/r/frnKYa3c",
    "hostedPageUrl": "https://twilee.local/p/frnKYa3c"
  },
  "links": [
    {
      "rel": "self",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e",
      "method": "GET"
    },
    {
      "rel": "https://twilee.com/rels/download",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/download",
      "method": "POST"
    },
    {
      "rel": "https://twilee.com/rels/schema-org",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/schemaorg",
      "method": "GET"
    },
    {
      "rel": "https://twilee.com/rels/scan-logs",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/scans",
      "method": "GET"
    },
    {
      "rel": "https://twilee.com/rels/page-views",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/page-views",
      "method": "GET"
    }
  ],
  "analytics": {
    "scans": 0,
    "views": 0
  }
}

Field reference

Field	Type	Description	Validation / Defaults
`id`	`string`	Unique identifier generated.	Read-only.
`name`	`string`	Human readable label.	Required, 1-255 chars.
`type`	`string`	Content type that defines the shape of `content`.	Defaults to `url`; must be one of `url`, `text`, `email`, `call`, `sms`, `geo`, `wifi`, `vcard`, `file`, `links`, `audio`, `event`.
`content`	`object`	Embedded content specific to the selected type.	Required fields depend on the type (see below).
`metadata`	`object`	Non-visual information such as tokens and timestamps.	Populated by the API; see Metadata below.
`appearance`	`object`	Visual styling of the rendered QR code.	See Appearance below.
`attributes`	`object`	Informational URLs and derived properties.	Read-only.
`links`	`array`	Actionable hypermedia relations (includes a `page-views` link only for hosted codes).	Read-only; varies per code.
`analytics`	`object`	Aggregated scan and view counters.	Read-only; `views` appears only for hosted codes.

Metadata

Field	Type	Description
`shortToken`	`string	null`
`createdAt`	`datetime`	ISO 8601 timestamp for creation.
`updatedAt`	`datetime`	ISO 8601 timestamp for the last update.

Appearance

The appearance object mirrors the options exposed in the Twilee designer. Properties are grouped by the renderer they control.

General

Field	Type	Description	Validation / Defaults
`shape`	`string`	Outline of the modules (`square` or `circle`).	Defaults to `square`; must be one of `square`, `circle`.
`predefinedImage`	`string,null`	Identifier or URL of a built-in logo.	Trimmed; must reference a configured logo key/URL.
`uploadedImage`	`string,null`	URL or path to a custom uploaded logo.	Optional.
`margin`	`int`	Canvas margin in pixels.	Defaults to `10`; must be ≥ 0.

QR options

Field	Type	Description	Validation / Defaults
`qrOptionsTypeNumber`	`int`	Version of the QR matrix.	Defaults to `0`; must be between 0 and 40.
`qrOptionsMode`	`string,null`	Encoding mode.	Optional; one of `Numeric`, `Alphanumeric`, `Byte`, `Kanji`.
`qrOptionsErrorCorrectionLevel`	`string`	Error-correction strength.	Defaults to `Q`; must be one of `L`, `M`, `Q`, `H`.

Image options

Field	Type	Description	Validation / Defaults
`imageOptionsHideBackgroundDots`	`bool`	Whether to remove dots covered by the center image.	Defaults to `true`.
`imageOptionsImageSize`	`float`	Size ratio of the center image.	Defaults to `0.4`; must be between 0 and 1.
`imageOptionsMargin`	`int`	Margin around the center image (px).	Defaults to `0`; must be ≥ 0.

Dots options

Field	Type	Description	Validation / Defaults
`dotsOptionsColor`	`string`	Color of the QR dots.	Defaults to `#000000`; must be 6-character hex.
`dotsOptionsType`	`string`	Shape template for dots.	Defaults to `square`; must be one of `rounded`, `dots`, `classy`, `classy-rounded`, `square`, `extra-rounded`.
`dotsOptionsRoundSize`	`bool`	Round dot sizes when rendering.	Defaults to `true`.
`dotsOptionsGradientType`	`string,null`	Gradient type for dots.	Optional; `linear` or `radial`.
`dotsOptionsGradientRotation`	`float,null`	Gradient rotation in radians.	Optional.
`dotsOptionsGradientColorStops`	`array,null`	Array of `{ offset, color }` entries for multi-color dots.	Optional.

Background options

Field	Type	Description	Validation / Defaults
`backgroundOptionsColor`	`string`	Canvas background color.	Defaults to `#ffffff`; must be 6-character hex.
`backgroundOptionsGradientType`	`string,null`	Background gradient type.	Optional; `linear` or `radial`.
`backgroundOptionsGradientRotation`	`float,null`	Background gradient rotation.	Optional.
`backgroundOptionsGradientColorStops`	`array,null`	Array of `{ offset, color }` entries for the background gradient.	Optional.

Corner square options

Field	Type	Description	Validation / Defaults
`cornersSquareOptionsColor`	`string,null`	Color of the position marker squares.	Optional; must be 6-character hex when provided.
`cornersSquareOptionsType`	`string,null`	Shape template for position marker squares.	Optional; one of `dot`, `square`, `extra-rounded`, `rounded`, `dots`, `classy`, `classy-rounded`.
`cornersSquareOptionsGradientType`	`string,null`	Gradient type for marker squares.	Optional; `linear` or `radial`.
`cornersSquareOptionsGradientRotation`	`float,null`	Gradient rotation for marker squares.	Optional.
`cornersSquareOptionsGradientColorStops`	`array,null`	Gradient stops for marker squares.	Optional.

Corner dot options

Field	Type	Description	Validation / Defaults
`cornersDotOptionsColor`	`string,null`	Color of the position marker dots.	Optional; must be 6-character hex when provided.
`cornersDotOptionsType`	`string,null`	Shape template for marker dots.	Optional; one of `dot`, `square`, `rounded`, `dots`, `classy`, `classy-rounded`, `extra-rounded`.
`cornersDotOptionsGradientType`	`string,null`	Gradient type for marker dots.	Optional; `linear` or `radial`.
`cornersDotOptionsGradientRotation`	`float,null`	Gradient rotation for marker dots.	Optional.
`cornersDotOptionsGradientColorStops`	`array,null`	Gradient stops for marker dots.	Optional.

Attributes

Field	Type	Description
`dynamicUrl`	`string,null`	Public redirect URL that resolves to the QR code target.
`hostedPageUrl`	`string,null`	Landing page hosted by Twilee when supported by the type.

Analytics

Field	Type	Description
`scans`	`int`	Total number of QR code scans.
`views`	`int,null`	Hosted page views (for hosted types).

Content Types (`content` payload)

Set the type field to one of the supported values below, then provide the matching content structure. The table summarises the payload returned by the API for each type:

Type (`type`)	Required `content` fields	Optional / Extra fields
`url`	`url`	—
`text`	`text`	`name`, `image`, hosted page colors (`hostedPageBackgroundColor`, `hostedPagePrimaryColor`), `publicFilePath`
`email`	`address`	`subject`, `message`
`call`	`phoneNumber`	—
`sms`	`phoneNumber`, `message`	—
`vcard`	varies (see below)	Support for names, job title, gender, note, organisation, address fields, `tel` (embedded call), `url` (embedded link), `email` (embedded email)
`file`	`fileName`	—
`links`	`links` (array of `{ url, name, image }`)	`name`, `image`, hosted page colors, `publicFilePath`
`audio`	`fileName`	`name`, `image`, hosted page colors, `publicAudioFilePath`
`event`	`name`, `startDate`, `endDate`	`eventType`, `image`, `location`, `description`, hosted page colors, `publicFilePath`

Note: Hosted page–capable types (text, links, audio, event) expose hostedPageBackgroundColor, hostedPagePrimaryColor, and publicFilePath fields so you can adjust landing page styling.

List QR Codes — `GET /qr_codes`

Retrieve a paginated list of all QR codes associated with your team.

curl -X GET "https://api.twilee.com/qr_codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response (JSON-LD)

{
  "@context": "/contexts/QrCode",
  "@id": "/qr_codes",
  "@type": "Collection",
  "totalItems": 1,
  "member": [
    {
      "@id": "/qr_codes/68cdbbe0ed096c7b590277c6",
      "@type": "QrCode",
      "id": "68cdbbe0ed096c7b590277c6",
      "name": "Redirects to https://twilee.com",
      "type": "url",
      "content": { "url": "https://twilee.com" },
      "metadata": { "shortToken": "frbORDRQ", "createdAt": "2024-05-01T09:15:24+00:00", "updatedAt": "2024-05-02T11:02:31+00:00" },
      "appearance": { "shape": "square", "predefinedImage": null, "uploadedImage": null, "margin": 10, "qrOptionsTypeNumber": 0, "qrOptionsMode": "Byte", "qrOptionsErrorCorrectionLevel": "Q", "imageOptionsHideBackgroundDots": true, "imageOptionsImageSize": 0.4, "imageOptionsMargin": 0, "dotsOptionsColor": "#000000", "dotsOptionsType": "square", "dotsOptionsRoundSize": true, "dotsOptionsGradientType": null, "dotsOptionsGradientRotation": null, "dotsOptionsGradientColorStops": null, "backgroundOptionsColor": "#ffffff", "backgroundOptionsGradientType": null, "backgroundOptionsGradientRotation": null, "backgroundOptionsGradientColorStops": null, "cornersSquareOptionsColor": null, "cornersSquareOptionsType": null, "cornersSquareOptionsGradientType": null, "cornersSquareOptionsGradientRotation": null, "cornersSquareOptionsGradientColorStops": null, "cornersDotOptionsColor": null, "cornersDotOptionsType": null, "cornersDotOptionsGradientType": null, "cornersDotOptionsGradientRotation": null, "cornersDotOptionsGradientColorStops": null },
      "attributes": { "dynamicUrl": "https://qr.twilee.com/r/frbORDRQ" },
      "links": [
        { "rel": "self", "href": "/qr_codes/68cdbbe0ed096c7b590277c6", "method": "GET" }
      ],
      "analytics": { "scans": 0 }
    }
  ]
}

Use the page query parameter for pagination:

GET /qr_codes?page=2

Retrieve a QR Code — `GET /qr_codes/{id}`

Fetch a single QR code belonging to the authenticated user’s team. The response body matches the structure shown in the Resource Representation section.

curl -X GET "https://api.twilee.com/qr_codes/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

If the QR code is not found, or belongs to another team, the API returns 400 Bad Request with the message “QR code not found”.

Schema.org Representation — `GET /qr_codes/{id}/schemaorg`

This endpoint exposes an alternative representation designed for structured data crawlers. The response groups the QR code metadata and the encoded content into two sections:

{
  "id": "68cdbbe0ed096c7b590277c6",
  "qrCode": {
    "@context": "https://schema.org",
    "@type": "BarCode",
    "identifier": "frbORDRQ",
    "name": "Redirects to twilee.com",
    "caption": "Scan me",
    "creator": { "@type": "Person", "name": "[email protected]" },
    "maintainer": { "@type": "Organization", "name": "My Team" },
    "dateCreated": { "@type": "DateTime", "dateCreated": "2024-05-01T09:15:24+00:00" },
    "description": "Campaign QR code",
    "provider": "Twilee"
  },
  "content": {
    "@context": "https://schema.org",
    "@type": "Event",
    "identifier": "frbORDRQ",
    "name": "Product Launch",
    "startDate": "2024-05-10T18:00:00+00:00",
    "endDate": "2024-05-10T21:00:00+00:00",
    "url": "https://twilee.com/p/frbORDRQ"
  }
}

Special handling is provided for event and vcard types, converting them into proper schema.org structures; other types return the raw embedded content payload.

Create a QR Code — `POST /qr_codes`

Create a new QR code by posting JSON data. Provide the fields described in the resource representation table above; unsupported keys are ignored.

curl -X POST "https://api.twilee.com/qr_codes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch landing page",
    "type": "url",
    "content": { "url": "https://twilee.com" },
    "appearance": {
      "shape": "circle",
      "margin": 12,
      "qrOptionsErrorCorrectionLevel": "H",
      "imageOptionsHideBackgroundDots": false,
      "dotsOptionsColor": "#111111",
      "dotsOptionsType": "rounded",
      "backgroundOptionsColor": "#f1f5f9",
      "cornersSquareOptionsType": "extra-rounded",
      "cornersSquareOptionsColor": "#111111"
    }
  }'

Validation highlights

name: 1–255 characters
type: one of the values in the enum (url, text, email, call, sms, geo, wifi, vcard, file, links, audio, event)
appearance.shape: must be square or circle
appearance.qrOptionsTypeNumber: integer between 0 and 40
appearance.qrOptionsMode: optional, but when provided must be Numeric, Alphanumeric, Byte, or Kanji
appearance.qrOptionsErrorCorrectionLevel: must be L, M, Q, or H
appearance.imageOptionsImageSize: floating value between 0 and 1
appearance.margin, appearance.imageOptionsMargin: zero or positive integers
Color fields (dotsOptionsColor, backgroundOptionsColor, cornersSquareOptionsColor, cornersDotOptionsColor): 6-character hex values (e.g., #123abc)
Enumerated style selectors (dotsOptionsType, cornersSquareOptionsType, cornersDotOptionsType): must use one of the values listed in the tables above

Successful creation returns 201 Created with the newly created resource in the response body.

Update a QR Code — `PUT /qr_codes/{id}`

Send a complete representation (or at least all fields you want to keep) to update an existing QR code. Validation rules match th ose for creation.

curl -X PUT "https://api.twilee.com/qr_codes/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated launch landing page",
    "type": "url",
    "content": { "url": "https://twilee.com" },
    "appearance": {
      "dotsOptionsColor": "#000000",
      "backgroundOptionsColor": "#ffffff"
    }
  }'

On success the API responds with 200 OK and the updated QR code payload.

Delete a QR Code — `DELETE /qr_codes/{id}`

Remove an existing QR code. A successful deletion returns 204 No Content.

curl -X DELETE "https://api.twilee.com/qr_codes/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Download a QR Code — `POST /qr_codes/{id}/download`

Trigger the generation of a QR code image for the specified resource. The call must be authenticated with an API key that is allowed to access the QR code's team.

curl -X POST "https://api.twilee.com/qr_codes/{id}/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -o qr-code.png \
  -d '{
    "format": "png",
    "size": 600,
    "margin": 10
  }'

Request body options

Field	Type	Default	Validation
`format`	`string`	`png`	Must be `png` or `svg`.
`size`	`int`	`300`	Must be between 10 and 5000 pixels.
`margin`	`int`	`10`	Must be between 0 and 30 pixels.

Notice: The download endpoint currently renders QR codes without applying the advanced appearance styling; expect default colors and shapes.

The response is a binary file with the appropriate filename derived from the QR code and selected format. Twilee automatically c leans up the temporary file after it is sent.

Error Handling

Validation errors respond with 400 Bad Request and a descriptive message (for example, invalid download options or missing co ntent fields).
Accessing a QR code that belongs to another team also produces 400 Bad Request (“QR code not found”) to avoid leaking existenc e of other resources.
Unauthorized requests return 401 Unauthorized, while authenticated users without access to the QR code receive 403 Forbidden.

With these operations you can programmatically manage Twilee QR codes end-to-end—from creation, customization, and analytics to s chema.org publishing and asset downloads.

QR Code Resource

Resource Representation

Field reference

Metadata

Appearance

Attributes

Analytics

Content Types (`content` payload)

List QR Codes — `GET /qr_codes`

Retrieve a QR Code — `GET /qr_codes/{id}`

Schema.org Representation — `GET /qr_codes/{id}/schemaorg`

Create a QR Code — `POST /qr_codes`

Update a QR Code — `PUT /qr_codes/{id}`

Delete a QR Code — `DELETE /qr_codes/{id}`

Download a QR Code — `POST /qr_codes/{id}/download`

Error Handling

Contact us

QR Code Resource

Resource Representation

Field reference

Metadata

Appearance

Attributes

Analytics

Content Types (content payload)

List QR Codes — GET /qr_codes

Retrieve a QR Code — GET /qr_codes/{id}

Schema.org Representation — GET /qr_codes/{id}/schemaorg

Create a QR Code — POST /qr_codes

Update a QR Code — PUT /qr_codes/{id}

Delete a QR Code — DELETE /qr_codes/{id}

Download a QR Code — POST /qr_codes/{id}/download

Error Handling

Contact us

Content Types (`content` payload)

List QR Codes — `GET /qr_codes`

Retrieve a QR Code — `GET /qr_codes/{id}`

Schema.org Representation — `GET /qr_codes/{id}/schemaorg`

Create a QR Code — `POST /qr_codes`

Update a QR Code — `PUT /qr_codes/{id}`

Delete a QR Code — `DELETE /qr_codes/{id}`

Download a QR Code — `POST /qr_codes/{id}/download`