Skip to content
API key

Getting started

Core concepts and URLs

QRBold’s vocabulary in plain English: which address does what, what the API hands back, and the pairs of things that are easy to confuse.

Environments and base URLs

There is one environment, production, and one base URL:

Base URL
https://api.qrbold.com/api/public/v1
  • No sandbox. There are no test keys and no test mode. A request you send creates real cards and real QR codes in your account.
  • HTTPS only.
  • The version is in the path. v1 is the current and only version. See versioning.
  • https://api.qrbold.com/api/v1 is not this API. That is the private API the dashboard itself uses. It takes a login session rather than an API key, has a different response shape, and changes without notice. Do not build on it.

Four kinds of URL

The four kinds of QRBold URL
KindExampleOpened byNeeds sign-in?
API endpointhttps://api.qrbold.com/api/public/v1/cardsYour serverAn API key
Dashboardhttps://qrbold.com/dashboardYouYour QRBold login
Public card URLhttps://qrbold.com/c/ada-lovelaceAnyoneNo
Public QR linkhttps://qrbold.com/p/spring-menuAnyoneNo

The first is what your code calls. The last two are what a QR code contains and what an end user’s phone opens. They are returned to you in the url field of a card or a QR code. If the account uses a custom domain, url uses that domain instead of qrbold.com.

How a scan travels

Creating something and somebody opening it are two separate journeys. First, creation:

  1. Your server

    Holds the API key

  2. QRBold API

    POST /cards

  3. Card object

    id, url, vcardUrl

  4. Your database

    Store the id and the url

Then, a scan of that card’s QR code:

  1. Printed QR code

    Contains the card’s url

  2. Phone camera

    Opens the url

  3. Public card page

    qrbold.com/c/… The scan is counted

And a scan of a dynamic URL code, which has one more hop:

  1. Printed QR code

    Contains the short link

  2. QRBold short link

    qrbold.com/p/… The scan is counted

  3. Your destination

    The destinationUrl you set, changeable any time

Your API key is involved in none of the scan journeys. Scans are counted on QRBold’s public page, and you read the totals later through analytics.

Ids and URLs

Most confusion comes from five pairs. In each, the left is for your code and the right is for people.

Card id

cmf3k2a9x0001

A permanent identifier. You pass it to the API to read, update or delete the card. Never shown to end users.

Card URL

https://qrbold.com/c/ada-lovelace

The public web page. This is what you share and what the card’s QR code contains.

QR code id

cmf3k4c2e0003

Identifies a QR code in API calls, including the call that downloads its image.

QR image

GET /qr-codes/cmf3k4c2e0003/image

The picture itself. There is no public image URL: you download the file with your key and host or print it.

API endpoint

https://api.qrbold.com/api/public/v1/cards/cmf3k2a9x0001

Returns JSON to your server. Needs a key.

Public URL

https://qrbold.com/c/ada-lovelace

Returns a web page to anyone. Needs nothing.

Short link

https://qrbold.com/p/spring-menu

The fixed address a QR code contains. It never changes, so the print never changes.

Destination URL

https://example.com/menu/spring

Where the short link forwards to. You can change it whenever you like.

Short code (slug)

ada-lovelace

The last part of a public URL. Random unless you choose one. Unique across all of QRBold.

Id

cmf3k2a9x0001

Assigned by QRBold and never chosen by you. Use the id, not the slug, in API paths.

Two more distinctions about actions rather than things:

  • Creating versus updating. POST makes a new thing and returns a new id. PATCH changes an existing thing and keeps its id and its URL. Sending the same POST twice makes two things unless you use an idempotency key.
  • A successful response versus a working result. 201 means the record exists. It does not prove a person can open it: check paused is false, then open url yourself.

The objects

Every JSON response has an object field naming what it is.

Objects returned by the API
objectWhat it isGuide
cardA digital business card: one person’s public profile.Create a card
card_templateA design, plus rules about which fields a card may set.Choose a template
qr_codeAny QR code in the account that is not a card.Dynamic QR codes
scan_statsScan totals and breakdowns for a period.Analytics
wallet_linksApple Wallet and Google Wallet links for a card.vCard and wallet
campaignA group that creates cards from your own JSON shape.Campaigns
listA page of any of the above, with pagination details.Pagination
api_key_contextWhat the key you sent is allowed to do.Quickstart

A card and a QR code are separate kinds of thing with separate endpoints. A card is not listed under /qr-codes, and a card id on /qr-codes/:id answers 404. The exceptions are the image and analytics endpoints, which accept either kind of id.

New fields may be added to any object at any time. Ignore the ones you do not recognise rather than failing on them.

Status and paused

Cards and QR codes have a status and a separate paused flag.

Status values
statusMeaningDoes the public URL open?
publishedLive. The default for anything the API creates.Yes
draftNot released yet.Yes, as a preview, if it has never been published. No, if it was published and then set back to draft.
pausedSwitched off on purpose, or parked by a plan limit.No. Visitors see a “not active” page.
archivedRetired and hidden from default lists.No

paused: true on an object means the account’s plan no longer covers it, for example after a downgrade. The record exists and its QR code is valid, but scanning it does not open the content. Nothing else in the response says so, which is why you should check it before printing.

Static and dynamic QR codes

A static QR code contains the final address itself. Change the address and you must reprint the code. Nothing in between can count scans.

A dynamic QR code contains a short link that forwards to the final address. You can change where it forwards without touching the print, and each scan passes through QRBold and is counted.

Every code the QRBold API creates is dynamic, and so is every card’s QR code. The API has no option to create a static code. The QR code guide compares the two in detail.