vCard QR code generator
A contact card as a QR code: scan it and the phone offers to save the contact, with the name, number, email, company and address already filled in. Useful on a business card, an email signature, a conference badge or a door sign.
What a contact code contains
A vCard is a small text document, and this page writes version 3.0 — the version phone address books import most reliably. Each line is a property:
- N holds the structured name in five semicolon-separated parts, and FN holds the display name. Both are written, because some readers use one and some the other.
- ORG and TITLE hold the company and the job title.
- TEL is marked as a cell number, so a phone files it correctly rather than as a landline.
- EMAIL and URL hold the address and website, with https:// added to a bare domain.
- ADR holds the address in the seven components the format defines, which is why an address typed into one box imports into the wrong fields elsewhere.
- NOTE holds anything left over.
Escaping and line folding
Semicolons and commas are structural in a vCard, so a company called Smith, Jones and Partners has to have its comma escaped or the reader sees two values where you meant one. Backslashes and line breaks need the same treatment. All four are escaped here.
vCard also limits a line to 75 octets and continues longer ones on a following line that begins with a space. Long addresses and notes are folded that way. The detail that matters is where the break lands: the count is in bytes but the break is only ever made between characters, because splitting a multi-byte character across a fold leaves two invalid bytes and a reader that either drops the character or rejects the whole card. That failure appears only with non-ASCII input, which is exactly why it survives in so many implementations.
A full card makes a dense code
A contact card with every field filled comes to around 340 bytes, which is a lot for a QR code. It fits — versions up to 40 are available — but a code holding 340 bytes has many more modules than one holding a URL, and each module is correspondingly smaller at the same printed size. On a business card that can be the difference between scanning at once and scanning on the third try.
So fill in what a person needs and leave the rest out. A name, one number, one email and a company is a code that scans from across a table. Adding a street address, a postcode, a job title and a note can double the payload. The byte counter shows the cost of each field as you type it, and level M with a shorter card usually beats level H with a longer one.
vCard or MeCard
MeCard holds the same core details in a much shorter form, so the code is less dense and scans more easily. It was designed for Japanese handsets, and Android reads it well while iOS support is less consistent.
Pick vCard when the code is going in front of an unknown audience — most importantly anyone on an iPhone — and MeCard when the code has to be physically small, is going on something awkward to scan, or is aimed at Android. Both are in the generator under Contact, so the honest way to choose is to make the code both ways and scan each with the phones you care about.
What happens when it is scanned
The phone shows the contact and offers to save it. It does not add anything silently, and it will not overwrite an existing contact without asking, which is why a contact code is a reasonable thing to print on a card.
What lands in which field varies between address books, and that is worth one test on a real phone before printing a thousand cards. The usual surprise is a name arriving in the wrong order, since N is structured and FN is display text, and readers disagree about which one wins.
Testing a contact importer
If you are on the receiving side, contact codes are a good source of the input that breaks importers. The interesting fixtures are a name with a comma in it, a company with a semicolon, a note long enough to fold across three lines, an address with an empty middle component, and any field containing characters outside ASCII. Each one exercises a rule that is easy to implement almost correctly.
The Developer content type takes an exact payload if you want to hand a reader something deliberately malformed — an unescaped semicolon, a fold in the middle of a character, a missing END line — and see whether it rejects the card or silently imports half of it.
Questions
Which vCard version does this write?
Version 3.0, which is what phone address books import most reliably. Version 4.0 is newer but support across mobile readers is patchier.
Should I use vCard or MeCard?
vCard for a general audience, particularly iPhone users. MeCard when the code must be small or the audience is on Android. Both are available, so make each and scan them with the phones that matter.
Why is my contact code so much denser than a URL code?
It holds far more text. A full card is around 340 bytes against perhaps 30 for a short link, and more bytes means more modules in the same space.
Does scanning add the contact automatically?
No. The phone shows the details and asks. Nothing is saved without the person scanning agreeing to it.
My name has an accent in it. Will it survive?
Yes. The text is encoded as UTF-8 and long lines are folded only between characters, so a multi-byte character is never split across a fold.
Can I put a photo in the code?
In practice, no. vCard allows an embedded image, but even a small one is far larger than a QR code can hold. Use the website field to point at a page carrying the photo.
Make a different kind of code
Invalid QR code generator · Damaged QR code generator · QR code testing tool · Free QR code generator · QR code generator for a URL · Wi-Fi QR code generator · QR code generator · Bulk QR code generator