Skip to content
API key

Guide

Short links and custom slugs

Every card and every QR code has a public link. This page explains how that link is built, how to choose the last part of it yourself, and what happens when the one you want is taken.

Anatomy of a public link

How public links are built
ForLinkWhat opens
A digital business cardhttps://qrbold.com/c/ada-lovelaceThe card page
A card’s contact filehttps://qrbold.com/c/ada-lovelace/vcardA .vcf download
A QR codehttps://qrbold.com/p/spring-menuA page that forwards to the destination

The last part, ada-lovelace or spring-menu, is the short code, also called the slug. The API returns it as shortCode and returns the whole link as url.

Always use url as given. Do not assemble a link from the short code yourself: the path differs between cards and QR codes, and the domain differs for accounts with a custom domain.

Choose your own slug

Send shortCode when you create a card or a QR code. Leave it out and you get a random 8-character code.

curl -X POST "https://api.qrbold.com/api/public/v1/cards" \
  -H "Authorization: Bearer $QRBOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "shortCode": "ada-lovelace",
    "fields": {
      "firstName": "Ada",
      "lastName": "Lovelace"
    }
  }'
  • Letters, numbers and hyphens only. No spaces, dots, underscores or slashes.
  • Up to 100 characters.
  • Unique across all of QRBold, not just your account. Common names go quickly, so plan for a taken slug.
  • A slug used by something in Trash is still in use.

The same field works on POST /qr-codes. A campaign is different: in mapped mode the campaign’s own short-link rule decides the slug, and in native mode an optional top-level shortCode does.

Taken and reserved slugs

A slug is never adjusted for you. If ada-lovelace is taken you do not get ada-lovelace-2; the request fails and nothing is created.

Slug errors
SituationStatuserror.code
The slug is already in use400invalid_request
The slug is a reserved word, such as login or dashboard400reserved_short_link
The slug has characters that are not allowed, or is too long422validation_failed
Two requests asked for the same slug at the same instant409already_exists
Campaign endpoint: the slug is taken409short_link_already_exists
Campaign endpoint: the slug is not valid422invalid_short_link
400 response
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "This short code / slug is already in use. Please choose another."
  }
}

A workable strategy when you generate slugs from names:

  1. Try the preferred slug.
  2. On a slug conflict, try one fallback you choose, such as the name plus an employee number.
  3. If that fails too, omit shortCode and accept a random one. The card still works.

There is no endpoint that checks whether a slug is free. Creating is the check.

Custom domains

An account can serve its public links from its own domain. That is set up in the dashboard; the API has no endpoints for adding or verifying a domain.

What an integration needs to know is small: when the account has a custom domain, the url and vcardUrl the API returns already use it, and the QR image encodes that same url. If you store and use url as given, custom domains need no code.

The API itself is always at api.qrbold.com, whatever domain the public links use.

Changing a slug

The API cannot change a slug after creation. PATCH /cards/:id accepts only fields and templateId, and PATCH /qr-codes/:id accepts only name, destinationUrl and status.

That restriction protects print. A QR code contains the link, so changing the slug of a printed code would break every copy of it. To send a printed QR code somewhere new, change its destination, not its slug.