The vCard Format Explained: Versions, Fields and Why Imports Break

Created on 16 November, 2026 • vCards & contact sharing • 4 views • 5 minutes read

vCard 2.1, 3.0 and 4.0, what each supports, how the file is actually structured, and the specific incompatibilities that mangle names, accents and phone numbers on import.

A vCard is a plain-text file describing a contact. It is what your phone exports when you share a contact, what a digital business card produces, and what gets attached to the bottom of a signature. The format is old, widely implemented, and implemented inconsistently - which is why contact imports so often arrive with the name in the wrong order and the accents replaced by question marks.

What the file looks like

A vCard is line-oriented text, one property per line, in the shape PROPERTY;PARAMETERS:VALUE. A minimal version 3.0 card:

BEGIN:VCARD
VERSION:3.0
N:Novak;Jane;;;
FN:Jane Novak
ORG:Novak Ceramics
TITLE:Founder
TEL;TYPE=CELL:+37060000000
EMAIL;TYPE=INTERNET:jane@example.com
URL:https://example.com
END:VCARD

Points worth noticing:

  • BEGIN, END and VERSION are required, and VERSION must come immediately after BEGIN.
  • N is the structured name, with five semicolon-separated components in a fixed order: family name, given name, additional names, honorific prefixes, honorific suffixes. Empty components are kept as empty strings, which is why the trailing semicolons are there.
  • FN is the formatted display name - the string a human should see. It is required, and it is a separate field precisely because name ordering differs between cultures.
  • Long lines are folded: a line break followed by a single space or tab continues the previous line. The specification asks for folding at 75 octets. Parsers that do not unfold correctly truncate values, which is one classic source of mangled imports.

The three versions

vCard 2.1 (1996, from the versit consortium). Still encountered in exports from older systems. Its defining quirk is character encoding: non-ASCII text is typically encoded with CHARSET and QUOTED-PRINTABLE parameters, and parsers that ignore those produce garbage for any accented character. If you are generating cards today, do not use 2.1.

vCard 3.0 (1998, RFC 2425 and RFC 2426). The interoperability sweet spot. Essentially every address book, CRM and phone can read it correctly. Types are expressed as parameters such as TEL;TYPE=CELL, and the preferred entry is marked with TYPE=PREF.

vCard 4.0 (2011, RFC 6350, which obsoletes RFC 2425, RFC 2426 and RFC 4770). The current standard and technically the best of the three. UTF-8 is mandatory - the specification states that specifying any other charset is invalid, which removes an entire class of encoding bugs. Preference is expressed numerically with PREF=1 rather than a type flag, and telephone values are expected to be tel: URIs, for example TEL;VALUE=uri;PREF=1;TYPE="voice,cell":tel:+1-555-555-5555.

Related serialisations exist for machine-to-machine use: xCard (XML) and jCard (JSON) carry the same data model in different syntax.

Which version to generate

The honest answer in 2026 is still 3.0 for anything a stranger's device will open, and 4.0 when you control both ends.

The reason is that 4.0 support remains uneven in the long tail of address books, CRMs and import tools, and the failure mode is bad: a parser that does not understand 4.0 may drop properties silently rather than erroring. If you are producing a digital business card to be scanned by whoever walks past your stand, 3.0 maximises the chance that the contact lands intact. If you are moving data between two systems you control and both support 4.0, use it and enjoy the mandatory UTF-8.

Whatever you choose, declare it honestly. A file labelled VERSION:3.0 that uses 4.0 syntax is worse than either.

The specific things that break

Names in the wrong order. Caused by relying on FN alone, or by filling N in the wrong order. Always populate both N and FN, and get the N component order right: family name first.

Accents turning into question marks or mojibake. Almost always a 2.1 file with quoted-printable encoding being read as plain text, or a 3.0 file saved in a local code page rather than UTF-8. Save as UTF-8, and prefer 3.0 or 4.0.

Phone numbers that do not dial. Store numbers in international E.164 form - a leading plus, country code, no spaces or punctuation. A number stored as (060) 000 000 is useless to anyone outside that country and may not dial from an imported contact.

Multiple cards in one file. A single .vcf can hold many cards, one BEGIN:VCARD/END:VCARD block after another. Some importers read only the first. If you are distributing one person's details, send one card per file.

Embedded photos bloating the file. A PHOTO property can carry a base64-encoded image inline. This is legal and routinely produces files hundreds of kilobytes in size, which is a problem if the card is delivered by QR code - see below. Prefer a PHOTO property containing a URI, or omit the photo.

Line endings. The specification calls for CRLF. Most parsers tolerate LF, but strict ones do not, and a file edited on one platform and parsed on another can fail for this alone.

Custom X- properties. Anything prefixed X- is a vendor extension. Useful within one ecosystem, invisible or discarded everywhere else. Do not put essential data there.

vCards in QR codes

Encoding a whole vCard directly into a QR code is popular for conference badges and business cards, and it works - but size is the constraint. A QR code's capacity tops out at 2,953 bytes of binary data, and long before that limit the code becomes dense enough that scanning gets unreliable at normal distances.

Keep an encoded card to the essentials: N, FN, ORG, TITLE, one TEL, one EMAIL, one URL. No photo, no notes, no addresses you do not need. The module-size consequences are explained in QR codes that actually scan.

The alternative is to encode a short link to a hosted contact page that offers a download, which keeps the code sparse and lets you update the details later - with the trade-off that it requires a network connection and a working service, as discussed in static versus dynamic QR codes. For a badge handed out at a single event, encoding the card directly is usually the better choice; for anything printed to last, the hosted page wins.

Testing

Test an import on at least one iOS device, one Android device, and whichever desktop mail client your audience uses. Test with a name containing non-ASCII characters, because that is where encoding bugs appear. And open the file in a plain text editor before shipping it - a vCard is readable text, and most defects are visible at a glance.