Create your first digital business card

A digital business card is a public web page for one person. It shows who they are and how to reach them, and it has a button that saves them to the visitor’s phone contacts. It lives at its own address, such as https://qrbold.com/c/ada-lovelace, and comes with a QR code that opens that address.

A card is made of two parts, and the API treats them differently:

• Data: the person’s name, title, company, photo, emails, phones, links, address and optional richer sections such as a gallery or testimonials. The API sets and changes this.
• Design: the layout, colours and which blocks appear. The API does not edit this. A card copies its design from a template when it is created, and after that the design is changed in the dashboard.

What is it?

A public profile page for one person, with a save-to-contacts button and its own QR code.

Why would I use it?

To give employees, sales reps or customers a card without anyone filling in a form by hand.

What do I need first?

An API key with cards:write. Optionally, a template designed in the dashboard.

Which endpoint do I use?

POST /cards with the person’s data.

What result should I expect?

A card object with a permanent id and a public url that opens immediately.

1. Pick a template

   Optional. GET /templates

2. Prepare the data

   The fields object

3. Create

   POST /cards

4. Save the id

   From the response

5. Open the url

   What people will see

1. 1
   Authenticate

   Send your key in the Authorization header.
2. 2
   Choose a template, or decide not to

   A template is optional.
3. 3
   Prepare the card data

   Build the fields object.
4. 4
   Send the create request

   POST /cards.
5. 5
   Check the response

   201, and paused is false.
6. 6
   Save the card id

   You need it for every later call.
7. 7
   Retrieve the card

   Confirm it reads back as you expect.
8. 8
   Find the public URL

   It is the url field. Nothing to construct.
9. 9
   Get the QR code

   Download the image with the card id.
10. 10
    Open the card and check it

    On a phone, signed out.

A template is optional. Leave templateId out and the card gets QRBold’s default starter design, with no rules about which fields you may set. That is the fastest way to a first card.

Use a template when every card should share your company’s design. Templates are built in the dashboard under Digital business cards → Templates; the API cannot create them. To find the id of one:

curl "https://api.qrbold.com/api/public/v1/templates" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "card_template",
      "id": "cmf3k1p7d0002",
      "name": "Company standard",
      "policy": {
        "theme": "locked",
        "blocks": "reorder_only",
        "fields": {
          "company": {
            "mode": "locked",
            "value": "Analytical Engines Ltd"
          },
          "firstName": {
            "mode": "required"
          }
        }
      },
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-20T14:12:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "hasMore": false
  }
}

The id is what you pass as templateId. Any template in your account works with any card; there is no compatibility to check.

What a template’s policy means

policy.fields lists rules for individual fields. Fields that are not listed are free to set.

In the example above, company is locked and firstName is required. The server enforces these rules for API requests exactly as it does in the dashboard.

All of a person’s data goes in one object called fields. Every field is optional as far as the API is concerned; a field becomes required only when the card’s template says so. In practice, send at least firstName and lastName: they become the card’s name.

• Text limits: short text fields take up to 200 characters, and bio and descriptions up to 2,000.
• URLs can be bare domains. example.com is accepted as well as https://example.com. mailto: and tel: links are accepted too.
• Images are links. photoUrl, coverUrl and companyLogoUrl must point at an image that is already public on the internet. The API has no upload.
• Link types: website, linkedin, x, instagram, facebook, youtube, github, whatsapp, calendly, tiktok, telegram, custom. Use custom with a label for anything else.
• Defaults: a field you leave out is simply absent from the card. Nothing is filled in for you unless the template pre-fills or locks it.
• Plans: no field is restricted to a particular plan. Plans limit how many cards an account may have, not what a card contains.

This request creates a complete card for a fictional person. Replace the values with your own, and replace or remove templateId and shortCode.

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 '{
    "name": "Ada Lovelace",
    "templateId": "cmf3k1p7d0002",
    "shortCode": "ada-lovelace",
    "status": "published",
    "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"
      }
    }
  }'

The request body, field by field

Headers

• Authorization: Bearer YOUR_API_KEY, required.
• Content-Type: application/json, required.
• Idempotency-Key, optional but recommended: any unique value, such as a UUID. If the request times out and you send it again with the same key, you get the original response back instead of a second card. See idempotency.

Success is 201 Created with the card object:

{
  "object": "card",
  "id": "cmf3k2a9x0001",
  "name": "Ada Lovelace",
  "shortCode": "ada-lovelace",
  "status": "published",
  "url": "https://qrbold.com/c/ada-lovelace",
  "vcardUrl": "https://qrbold.com/c/ada-lovelace/vcard",
  "templateId": "cmf3k1p7d0002",
  "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"
}

A card is live when status is published and paused is false. Check both before you print anything.

Common errors

A template violation looks like this. Every problem is listed at once:

{
  "error": {
    "type": "invalid_request",
    "code": "validation_failed",
    "message": "Some fields could not be saved.",
    "details": [
      {
        "key": "company",
        "reason": "locked"
      },
      {
        "key": "firstName",
        "reason": "required"
      }
    ]
  }
}

Creating a card, publishing it and creating its QR code are therefore one operation in QRBold, not three. The only separate step is downloading the QR image.

By id:

curl "https://api.qrbold.com/api/public/v1/cards/cmf3k2a9x0001" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

It returns the same card object as creation. If you did not store the id, find the card by name with the list endpoint. search matches part of the name:

curl "https://api.qrbold.com/api/public/v1/cards?search=Lovelace" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

Lists are paged, 25 at a time by default. See pagination.

So the safe way to change one thing is read, modify, write:

1. GET /cards/:id and take its fields.
2. Change what you need in that object.
3. PATCH /cards/:id with the whole object.

This example changes Ada’s title and keeps everything else:

curl -X PATCH "https://api.qrbold.com/api/public/v1/cards/cmf3k2a9x0001" \
  -H "Authorization: Bearer $QRBOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "fields": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "title": "Chief Technology Officer",
      "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"
      }
    }
  }'

• The card’s id, url and QR code do not change. Nothing needs reprinting.
• The card’s name follows the person’s name automatically.
• Only fields and templateId can be sent. Status, slug and design cannot be changed through the API; an unknown key here answers 422.
• The template’s rules apply to updates just as they do to creation.

curl -X DELETE "https://api.qrbold.com/api/public/v1/cards/cmf3k2a9x0001" \
  -H "Authorization: Bearer $QRBOLD_API_KEY"

It answers 204 with no body. The card moves to the account’s Trash, and three things follow:

• Its public URL stops opening straight away, and visitors see an “unavailable” page.
• Its QR code stops working too, because the QR code points at that URL. A printed code for a deleted card leads nowhere.
• It can be restored from Trash in the dashboard for 30 days, which brings the URL and the QR code back. The API cannot restore it.

There is no “deactivate” in the card API. To take a card offline without deleting it, pause or unpublish it in the dashboard.

Open the url from the response, for example https://qrbold.com/c/ada-lovelace, and check:

• The page opens in a private browser window, where you are not signed in to QRBold.
• The name, title, photo and contact details are the ones you sent.
• The save-contact button downloads a contact. You can test the file directly at vcardUrl.
• It reads well on a phone, since that is where almost every visitor will see it.
• The same card appears in the dashboard under Digital business cards.

Next: generate the QR code for this card, using the id you just saved (cmf3k2a9x0001 in these examples).