Generate a QR code for your digital business card

There are two different jobs, and they use different endpoints:

1. Card

   POST /cards returns id and url

2. QR image

   GET /qr-codes/{card id}/image

3. Print or display

   Badge, email signature, packaging

4. Scan

   The phone opens the card’s url

What is it?

The QR picture for a card, as a file.

Why would I use it?

To print it or show it, so that a scan opens the card.

What do I need first?

The card’s id, and a key with cards:read or qr:read.

Which endpoint do I use?

GET /qr-codes/:id/image, with the card id in place of :id.

What result should I expect?

The response body is the image itself, not JSON. Save it to a file.

This downloads a 1024-pixel PNG for the example card cmf3k2a9x0001 and saves it as qr.png:

curl "https://api.qrbold.com/api/public/v1/qr-codes/cmf3k2a9x0001/image?format=png&size=1024" \
  -H "Authorization: Bearer $QRBOLD_API_KEY" \
  --output qr.png

• What the code contains: exactly the card’s url field. Nothing else is encoded, and no personal data is stored in the picture.
• Updating the card does not change the code. The code points at the card’s address, and the address stays the same when the card’s content changes.
• The response is binary. Do not call res.json() on it. Read it as bytes, as the samples do.

All four are optional query parameters.

Choosing a format

Choosing a size

• size is the width in pixels, from 128 to 4096. The default is 512.
• For print, allow about 300 pixels per inch: a code printed 2 inches (5 cm) wide needs size=600 or more. Or use svg or pdf and stop thinking about pixels.
• A code with a frame around it is taller than it is wide, so do not assume a square.
• As a rule of thumb, print a code no smaller than 2 cm (0.8 in) across, and keep a blank margin around it.

An SVG with a transparent background, for a designer:

curl "https://api.qrbold.com/api/public/v1/qr-codes/cmf3k2a9x0001/image?format=svg&transparent=true" \
  -H "Authorization: Bearer $QRBOLD_API_KEY" \
  --output qr.svg

Responses may be cached privately for an hour. If you change a code’s design in the dashboard, allow for that before expecting a new picture from a cache.

The API cannot set a QR code’s appearance. There are no parameters for colours, dot shapes, a logo, a frame or error correction. The only things a request controls are the file format, the pixel size and whether the background is transparent.

The image endpoint draws the code with whatever design is saved for it in the dashboard. So the workflow for a branded code is:

1. Open the card or the QR code in the dashboard and design its QR code there.
2. Save.
3. Download the image through the API. It comes back with that design.

A code that has never been designed is plain black on white. When many cards should share a look, check one downloaded image before generating the rest.

What is it?

A QR code that sends people to a URL you choose, through a QRBold short link.

Why would I use it?

For menus, packaging, posters and anything printed whose destination may change later.

What do I need first?

A key with qr:write, and a full https:// address to send people to.

Which endpoint do I use?

POST /qr-codes with a name and a destinationUrl.

What result should I expect?

A qr_code object with an id, and a url that is the short link the picture will contain.

curl -X POST "https://api.qrbold.com/api/public/v1/qr-codes" \
  -H "Authorization: Bearer $QRBOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Spring menu",
    "destinationUrl": "https://example.com/menu/spring",
    "shortCode": "spring-menu"
  }'

Unlike card creation, this endpoint is strict: a key it does not recognise answers 422.

{
  "object": "qr_code",
  "id": "cmf3k4c2e0003",
  "name": "Spring menu",
  "type": "url",
  "status": "published",
  "shortCode": "spring-menu",
  "url": "https://qrbold.com/p/spring-menu",
  "destinationUrl": "https://example.com/menu/spring",
  "paused": false,
  "scanCount": 0,
  "createdAt": "2026-10-09T09:35:00.000Z",
  "updatedAt": "2026-10-09T09:35:00.000Z"
}

Then download the picture, this time with the QR code’s id:

curl "https://api.qrbold.com/api/public/v1/qr-codes/cmf3k4c2e0003/image?format=png&size=1024" \
  -H "Authorization: Bearer $QRBOLD_API_KEY" \
  --output qr.png

What happens on a scan

1. Scan

   The phone opens the short link

2. QRBold

   Counts the scan

3. Destination

   The browser is sent on to destinationUrl

The forwarding is done by a small QRBold page in the visitor’s browser, not by an HTTP 301 or 302 response. For a person scanning with a phone there is no visible difference. For a script it matters: fetching the short link with cURL returns an HTML page and does not follow through to your destination, so test with a real browser or a real phone.

To point a printed code somewhere new, send only the new destination. Fields you leave out stay as they are, which is the opposite of how a card update behaves.

curl -X PATCH "https://api.qrbold.com/api/public/v1/qr-codes/cmf3k4c2e0003" \
  -H "Authorization: Bearer $QRBOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationUrl": "https://example.com/menu/summer"
  }'

• Only url codes can be re-pointed. Sending destinationUrl for a file, page or GS1 code answers 422.
• The short code of an existing code cannot be changed through the API.
• A card’s status cannot be changed through the API at all. Pause or unpublish a card in the dashboard.

Every code this API creates is dynamic, and so is every card’s code. If you need a static code, encode the address directly with any QR library; QRBold is not involved and cannot report on it.

Do this with one code before you generate a thousand.

• The image file opens and shows a QR code.
• A phone camera recognises it at the size you will actually print or display.
• It opens the address in the object’s url field.
• The correct card, or the correct destination, appears.
• It works in a private browser window and on a phone that is not signed in to QRBold.
• paused is false on the card or code object.
• The scan shows up in analytics a short while later.
• For a dynamic code: change the destination, scan again, and confirm the new page opens.
• For print: test a proof on the real material. Gloss, curves and low contrast all make scanning harder.

The end-to-end tutorial puts card creation and the QR download together in one script.