Create a digital business card and QR code from scratch

export QRBOLD_API_KEY="qrb_live_your_key_here"

$env:QRBOLD_API_KEY = "qrb_live_your_key_here"

{
  "object": "card",
  "id": "cmf3k2a9x0001",
  "name": "Ada Lovelace",
  "shortCode": "k3Vq8ZtB",
  "status": "published",
  "url": "https://qrbold.com/c/k3Vq8ZtB",
  "vcardUrl": "https://qrbold.com/c/k3Vq8ZtB/vcard",
  "templateId": null,
  "externalId": null,
  "paused": false,
  "fields": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "title": "Head of Engineering",
    "company": "Analytical Engines Ltd",
    "photoUrl": "https://example.com/photos/ada.jpg",
    "companyLogoUrl": "https://example.com/brand/logo.png",
    "bio": "Builds calculating machines and the teams around them.",
    "emails": [
      {
        "label": "Work",
        "value": "ada@example.com"
      }
    ],
    "phones": [
      {
        "label": "Mobile",
        "value": "+44 20 7946 0958"
      }
    ],
    "links": [
      {
        "type": "website",
        "url": "example.com"
      },
      {
        "type": "linkedin",
        "url": "linkedin.com/in/ada-lovelace"
      }
    ],
    "address": {
      "city": "London",
      "country": "United Kingdom"
    }
  },
  "createdAt": "2026-10-09T09:30:00.000Z",
  "updatedAt": "2026-10-09T09:30:00.000Z"
}

// create-card.mjs
// Creates a digital business card, reads it back and saves its QR code.
// Run with:  node create-card.mjs        (Node.js 20 or later, no packages)

import { randomUUID } from 'node:crypto';
import { writeFile } from 'node:fs/promises';

const BASE_URL = 'https://api.qrbold.com/api/public/v1';
const API_KEY = process.env.QRBOLD_API_KEY;

if (!API_KEY) {
  console.error('Set the QRBOLD_API_KEY environment variable first.');
  process.exit(1);
}

// One helper for every request: adds the key, checks the status, and turns a
// failure into an Error that carries the API's own code and message.
async function qrbold(method, path, { body, idempotencyKey } = {}) {
  const res = await fetch(BASE_URL + path, {
    method,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(30_000),
  });

  if (!res.ok) {
    // Most errors are { error: { type, code, message, details } }. A 429 is not,
    // so fall back to the status.
    const problem = await res.json().catch(() => null);
    const error = new Error(problem?.error?.message ?? problem?.message ?? res.statusText);
    error.status = res.status;
    error.code = problem?.error?.code ?? null;
    error.details = problem?.error?.details ?? null;
    throw error;
  }
  return res;
}

async function main() {
  // 1. Check the key. GET /me needs no scope and changes nothing.
  const me = await (await qrbold('GET', '/me')).json();
  console.log(`Key "${me.key.name}" is valid for ${me.account.email}`);

  // 2. Create the card. The Idempotency-Key makes a retry of this exact
  //    request return the same card instead of creating a second one.
  const created = await (
    await qrbold('POST', '/cards', {
      idempotencyKey: randomUUID(),
      body: {
        fields: {
          "firstName": "Ada",
          "lastName": "Lovelace",
          "title": "Head of Engineering",
          "company": "Analytical Engines Ltd",
          "photoUrl": "https://example.com/photos/ada.jpg",
          "companyLogoUrl": "https://example.com/brand/logo.png",
          "bio": "Builds calculating machines and the teams around them.",
          "emails": [
            {
              "label": "Work",
              "value": "ada@example.com"
            }
          ],
          "phones": [
            {
              "label": "Mobile",
              "value": "+44 20 7946 0958"
            }
          ],
          "links": [
            {
              "type": "website",
              "url": "example.com"
            },
            {
              "type": "linkedin",
              "url": "linkedin.com/in/ada-lovelace"
            }
          ],
          "address": {
            "city": "London",
            "country": "United Kingdom"
          }
        },
      },
    })
  ).json();

  console.log('Created card', created.id);
  console.log('Public URL  ', created.url);

  if (created.paused || created.status !== 'published') {
    console.warn('The card exists but is not live. Check the plan in the dashboard.');
  }

  // 3. Read it back by id, the way your application will later.
  const card = await (await qrbold('GET', `/cards/${created.id}`)).json();
  console.log('Retrieved   ', card.name);

  // 4. Download the QR code. The card's own id is used: no separate QR code
  //    is created. The response is the image itself, not JSON.
  const image = await qrbold('GET', `/qr-codes/${card.id}/image?format=png&size=1024`);
  await writeFile('card-qr.png', Buffer.from(await image.arrayBuffer()));
  console.log('Saved card-qr.png');

  console.log(`\nScan card-qr.png with a phone. It should open ${card.url}`);
}

main().catch((error) => {
  console.error(`Failed: ${error.status ?? ''} ${error.code ?? ''} ${error.message}`);
  if (error.details) console.error(JSON.stringify(error.details, null, 2));
  process.exit(1);
});

Key "HR onboarding sync" is valid for you@example.com
Created card cmf3k2a9x0001
Public URL   https://qrbold.com/c/k3Vq8ZtB
Retrieved    Ada Lovelace
Saved card-qr.png

Scan card-qr.png with a phone. It should open https://qrbold.com/c/k3Vq8ZtB