Skip to main content
BitlyDeveloper
Start Now

Generate QR Codes

You can create a QR Code for any URL that you want via the API and customize it with a variety of different options.

Refer to the Create Endpoint for a detailed breakdown of the customizations that are available when creating a QR Code. QR Code colors and file type options may be available depending on your subscription plan.

There are multiple examples in the dropdown for the request which show a variety of QR Code customizations. We recommend taking a look at the available customizations in the Bitly web app for a visual preview of what's available.

Creating a Stand Alone Bitly Code

A stand alone QR Code is a QR Code that is created with a long_url rather than an existing bitlink_id. This means the QR Code is not tied to a Bitly short link and only consumes your QR Code limit, not your Link limit.

The Create QR Code endpoint can create codes with a large variety of customizations, but if a standard black and white QR Code is what you want, the minimum amount of data required is as follows:

POST /v4/qr-codes
{
  "title": "Stand Alone QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "long_url": "https://example.com/page"
  }
}

Creating a QR Code in this way will only consume 1 QR Code from your monthly limit, not a Link.

You can see more examples of stand alone Bitly Code creation in the API Reference, including the "Stand Alone QR Code" example in the request examples dropdown.

Creating a Coupled QR Code

Creating a QR Code from a bitlink is very similar to creating a stand alone QR Code. After creating a short link you can set it as the QR Code's destination using the bitlink_id property instead of long_url:

POST /v4/qr-codes
{
  "title": "Minimal Bitlink QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "bitlink_id": "bit.ly/abc123"
  }
}

Creating a QR Code in this way will only consume 1 QR Code from your monthly limit, a Link will be consumed when you create the link, if you use an existing link it would not consume a link limit, only the QR Code limit.

Request Body

The request body is briefly described below and in more detail in the Create Endpoint.

title string A title to name the QR Code.

destination object This determines where the QR Code scan is redirected.

render_customizations object Change the colors, shapes, add logos, and more. This object determines what the QR Code will look like.

You can specify the color of almost any element of the QR Code. There are multiple shapes for the different elements of the QR Code.

Let's create another QR Code with some customization options set. We'll set the dot pattern option to rounded and adjust the shape of each corner to leaf. We'll also use two gradients, one for the background, and one for the color of the QR dots.

POST /v4/qr-codes
{
  "title": "Gradient QR Code",
  "group_guid": "Ba1bc23dE4F",
  "destination": {
    "bitlink_id": "bit.ly/abc123"
  },
  "render_customizations": {
    "dot_pattern_type": "rounded",
    "corners": {
      "corner_1": { "shape": "leaf" },
      "corner_2": { "shape": "leaf" },
      "corner_3": { "shape": "leaf" }
    },
    "gradient": {
      "style": "linear",
      "angle": 45,
      "colors": [
        { "color": "#C80404", "offset": 10 },
        { "color": "#042F86", "offset": 90 }
      ],
      "exclude_corners": false
    },
    "background_gradient": {
      "style": "radial",
      "colors": [
        { "color": "#C696EE", "offset": 25 },
        { "color": "#D4E1A8", "offset": 50 }
      ]
    }
  }
}

A successful response will return metadata about the QR Code.

{
  "qrcode_id": "string",
  "group_guid": "string",
  "title": "string",
  "archived": "boolean",
  "created": "string",
  "modified": "string"
}

Creating a Static QR Code

A static QR Code encodes a URL directly into an image without creating or saving a QR Code resource. This is useful when you want an image immediately without consuming your QR Code limit.

This feature requires account enablement. Contact your Account Manager to discuss enabling static QR Code creation as an add-on to your subscription plan.

The minimum required data is a content URL and a group_guid:

POST /v4/qr-codes/static
{
  "content": "https://example.com/page",
  "group_guid": "Ba1bc23dE4F"
}

Creating a static QR Code does not consume your QR Code limit or your Link limit. However, it does consume a static QR Code limit. This limit is configurable and can be set after discussing your needs with your Account Manager.

content string The URL to encode in the QR Code.

group_guid string The group GUID used for access control.

render_customizations object Change the colors and shapes of the QR Code.

Static QR Codes support a subset of customization options. The following are not supported: gradient, background_gradient, frame, text, and logo.

Let's create a static QR Code with some customization options. We'll set the dot pattern to rounded, adjust the shape of each corner to leaf, and set custom colors.

POST /v4/qr-codes/static
{
  "content": "https://example.com/page",
  "group_guid": "Ba1bc23dE4F",
  "render_customizations": {
    "background_color": "#ffffff",
    "dot_pattern_color": "#EF8000",
    "dot_pattern_type": "rounded",
    "corners": {
      "corner_1": { "inner_color": "#EF8000", "outer_color": "#EF8000", "shape": "leaf" },
      "corner_2": { "inner_color": "#EF8000", "outer_color": "#EF8000", "shape": "leaf" },
      "corner_3": { "inner_color": "#EF8000", "outer_color": "#EF8000", "shape": "leaf" }
    }
  }
}

The Accept request header controls the response format:

  • application/json (default): Returns a JSON object with the image as a base64-encoded string.
  • image/svg+xml: Returns the raw SVG image.
  • image/png: Returns the raw PNG image.

You can also use the format query parameter (svg or png) to specify the image format when using the default JSON response.

A successful application/json response returns the image as a base64-encoded string:

{
  "image": "PHN2ZyB4bWxucz0iaHR0cDov..."
}

To receive the raw SVG image directly, set the Accept header to image/svg+xml:

POST /v4/qr-codes/static
Accept: image/svg+xml
{
  "content": "https://example.com/page",
  "group_guid": "Ba1bc23dE4F"
}

The subsequent endpoints apply to QR Codes created via POST /v4/qr-codes. Static QR Codes created via POST /v4/qr-codes/static are not saved as resources and cannot be retrieved or modified after creation.

Retrieve QR Code Image

Once the code has been created successfully we can grab the image data from the following endpoint.

GET /v4/qr-codes/{qrcode_id}/image

The response is returned as SVG by default.

Interacting with a QR Code

Once a QR Code has been created you can retrieve its details with:

GET /v4/qr-codes/{qrcode_id}

To make changes to your QR code use:

PATCH /v4/qr-codes/{qrcode_id}

This endpoint allows you to update the QR Code's:

  • title
  • render customizations
  • archived/unarchived