How to make a contact (vCard) QR code

Write a short vCard (or MECARD) with the details you want to share, escape special characters, and test the code before you print it.

A contact QR code holds your details as plain text in the vCard (or the shorter MECARD) format, and when someone scans it, their phone offers to save you as a contact. Write a short vCard with only the fields you want to share, escape special characters, and test the code before you print it.

What’s inside a contact code

The code doesn’t link anywhere: the contact details are the text inside it. Two formats are common:

  • vCard, the format contact apps use to exchange contacts. Version 3.0 is defined in RFC 2426 and version 4.0 in RFC 6350.
  • MECARD, a one-line format popularized by NTT Docomo for barcodes. It’s more compact but holds fewer fields.

A minimal vCard

BEGIN:VCARD
VERSION:3.0
N:Rivera;Sam;;;
FN:Sam Rivera
ORG:Example Studio
TITLE:Designer
TEL;TYPE=WORK,VOICE:+1-555-0100
EMAIL;TYPE=WORK:sam@example.com
URL:https://example.com
END:VCARD

Each line is one property. VERSION comes right after BEGIN:VCARD. Write phone numbers in international form (+ and the country code) so they work for people in other countries.

The fields that matter

Field What it holds Notes
N Structured name Family name; given name; additional names; prefix; suffix, separated by ;
FN Display name The name as it should appear, e.g. Sam Rivera
TEL Phone number Add TYPE=WORK, CELL or HOME if you like
EMAIL Email address One is usually enough
ORG Company Departments can follow after ;
TITLE Job title Plain text
URL Website A full address with https://
ADR Postal address Seven parts: PO box; extended; street; city; region; postal code; country

An address with all its parts looks like this: ADR;TYPE=WORK:;;12 Main Street;Springfield;IL;62701;USA.

vCard 3.0 or 4.0

  • Required fields. Version 3.0 requires N, FN and VERSION. Version 4.0 requires only FN and VERSION, and recommends N.
  • Character set. Version 4.0 is UTF-8 only. Version 3.0 prefers UTF-8.
  • Phone numbers. Version 4.0 can write a number as a tel: URI (TEL;VALUE=uri:tel:+1-555-0100); version 3.0 writes it as text.

If you aren’t sure, write version 3.0 with both N and FN: it reads well in common contact apps and stays valid if a reader expects either.

Escaping and special characters

In text values, a few characters have a special meaning, so they’re written with a backslash in front:

  • a comma as \, (for example ORG:Smith\, Jones & Co)
  • a semicolon as \;, because ; separates the parts of N, ADR and ORG
  • a backslash as \\
  • a line break as \n

Names with accents or in non-Latin scripts are fine as long as the text is encoded as UTF-8. A QR code stores bytes, and a scanner has to work out which character set they’re in, so test codes with non-ASCII names on a couple of phones.

MECARD: the compact alternative

MECARD:N:Rivera,Sam;TEL:+15550100;EMAIL:sam@example.com;URL:https://example.com;;

The name is written Last,First, each field ends with ;, and the record ends with ;;. Escape \, ;, , and : with a backslash. MECARD saves characters but covers fewer fields than vCard, and not all camera apps treat the two formats the same way, so test it on the phones your audience uses.

Keep it short

Every character you add makes the code denser: more modules, smaller dots at the same print size, and a harder scan from a distance or in poor light. To keep the code easy to read:

  • Leave out fields people won’t use, such as a second phone number or a long note.
  • Don’t embed a photo. A base64 picture makes the code far too large.
  • Put the extras (portfolio, booking page, social profiles) behind one URL.
  • Use error correction level M unless the code will be scuffed or partly covered.

If the code has to be small, see QR code size for printing for how density and scanning distance affect size.

What happens when someone scans it

Phone camera apps and scanner apps recognize the BEGIN:VCARD or MECARD: start and show the name with an option to save the contact. Nothing is added until the person confirms, and they can edit the details first. In QR App for Android, a scanned contact shows its fields, and Save contact hands it to your contacts app.

Privacy: anyone can scan it

A printed code is readable by anyone who sees it, including anyone with a photo of it. On a business card, a name badge or a poster:

  • Use your work phone and work email rather than personal ones.
  • Use an office address, or leave the address out. Don’t put a home address on a public code.
  • Remember that a static code can’t be changed after printing. If your details change, make a new code. Static vs dynamic QR codes explains the trade-off.

Making the code

  • In a browser: paste your vCard into the generator. It encodes exactly the text you type, as UTF-8, and runs in your browser, so the details aren’t uploaded. Download an SVG for print or a PNG for screens.
  • On Android: QR App’s Contact type has fields for first and last name, phone, email, organization, title, address and website, and writes a vCard 3.0 with the escaping done for you. From contacts fills the form from Android’s contact picker: the app gets only the contact you pick and doesn’t ask for access to your contacts.

Whichever you use, scan the result with two or three phones and check the name, number and email before you print a batch.

Questions and answers

Can a contact QR code include my photo?

vCard has a PHOTO field, but an embedded picture adds far more data than a QR code can comfortably hold. Put a link to a web page with your photo in the URL field instead.

Does scanning a contact code add the contact by itself?

No. Phones show the details first and add the contact only when the person taps save, and they can edit it before saving.

Can I change the details after printing the code?

Not in a static code: the details are inside the code itself. If your phone number or job changes, make a new code and reprint it.

Why do accented letters look wrong after scanning?

The text was probably not encoded as UTF-8, or the scanner guessed the encoding wrongly. Make the code from UTF-8 text and test it with a few different phones before printing.

Should I use vCard 3.0 or 4.0?

Both are read by common contact apps. Version 3.0 is a frequent choice for QR codes because contact apps have read it for a long time; version 4.0 is the current standard and uses UTF-8 only.

Sources