The vCard Format — Syntax, Properties and Version Differences

The shape of a vCard

A .vcf file is a sequence of cards. There is no envelope, no index, no catalog at the top. Each card is a block that starts with BEGIN:VCARD and ends with END:VCARD. The first property inside is VERSION, which is the dialect for that card — 2.1, 3.0 or 4.0. A file that mixes versions is legal; each block is parsed on its own VERSION line. Line endings are CRLF (\r\n), which is what RFC 2426 and RFC 6350 require and what this site's generator writes.

Everything between VERSION and END is a property line. The grammar is:

[group.]NAME[;PARAM=value][;PARAM=value…]:value

Dissected, left to right. The optional group is a token plus a dot — iCloud writes item1.TEL instead of plain TEL; a parser that wants the property name strips everything through the first dot. NAME is the property (FN, TEL, EMAIL, …), case-insensitive. Each ;PARAM=value is a parameter; 2.1 also allows a bare token with no = (TEL;CELL:). The colon is the delimiter that ends the name-and-params side. Parameters can contain quoted strings, so the colon that counts is the first one that is not inside double quotes. The rest of the line is the value.

A complete, legal vCard 3.0 — the dialect Google Contacts and iCloud export, and the dialect this site writes by default:

BEGIN:VCARD
VERSION:3.0
N:Chen;Maya;Li;;
FN:Dr. Maya Li Chen PhD
ORG:Northwind Labs
TITLE:Product Manager
TEL;TYPE=CELL:+14155550123
EMAIL;TYPE=INTERNET;TYPE=PREF:maya@northwind.example
ADR;TYPE=HOME:;;1 Market St;San Francisco;CA;94105;USA
URL:https://northwind.example
NOTE:Prefers email. Do not call after 18:00.
END:VCARD

Line by line:

• BEGIN:VCARD — start of this card. A file with two hundred contacts is this block, then another, then another.
• VERSION:3.0 — the grammar for every line that follows on this card. Do not put 2.1 TYPE syntax under a 3.0 VERSION, or 4.0 lowercase TYPE under a 3.0 VERSION.
• N:Chen;Maya;Li;; — the structured name. Five slots, semicolon-separated; the last two (prefix, suffix) are empty here, so the trailing semicolons stay. See the next section for the five-part layout.
• FN:Dr. Maya Li Chen PhD — required in 3.0 and 4.0. This is what the address-book list shows.
• TEL;TYPE=CELL:+14155550123 — name, one parameter, value. On 2.1 this same fact is TEL;CELL:+14155550123; on 4.0 it is TEL;TYPE=cell:+14155550123.
• EMAIL;TYPE=INTERNET;TYPE=PREF:maya@northwind.example — two parameters. The first email on a 3.0 card from this site's generator gets TYPE=PREF; 4.0 writes PREF=1 instead.
• ADR;TYPE=HOME:;;1 Market St;San Francisco;CA;94105;USA — seven slots (PO box, extended, street, city, region, postal, country). The empty PO box and extended slots still take a semicolon each, which is why the value starts with ;;.
• END:VCARD— end of this card. The next line, if any, is the next card's BEGIN.

Long lines are a serialization detail, not extra properties. A parser unfolds first (join a line that starts with a space or tab onto the previous line; for 2.1 quoted-printable, also join a line that ended in =), then splits on the property colon. If you are reading a file in an editor and a value looks truncated, look at the next physical line — it is probably a fold.

Property reference

The properties you will actually write or trip over. Syntax is shown in the 3.0 dialect unless the version column says otherwise. This site's generator emits N, FN, ORG, TITLE, TEL, EMAIL, ADR, URL and NOTE; it does not write BDAY, PHOTO, UID or REV. The parser reads BDAY into a birthday field and ignores PHOTO, UID, REV and any other unknown name.

N is the one that is worth slowing down for. The value is always five components, in this order:

A legal 3.0 card that actually fills all five slots, next to the FN a phone should show:

BEGIN:VCARD
VERSION:3.0
N:Chen;Maya;Li;Dr.;PhD
FN:Dr. Maya Li Chen PhD
END:VCARD

N:Chen;Maya;Li;Dr.;PhD is not the same as FN:Dr. Maya Li Chen PhD. N is for sorting and for reconstructing a name in a locale that wants family-name first. FN is the string you already formatted. If you only have a display name and no structured parts, still write both: put the display name in FN, and put a best-effort split in N (this site's generator, given only a full name, takes the last word as family and the rest as given).

Empty slots are not optional punctuation. N:Chen;Maya is two components, not five — a strict parser will not invent empty prefix and suffix for you. Write N:Chen;Maya;;; when middle, prefix and suffix are blank. A semicolon inside a component (a last name like Smith;Jones) is escaped as Smith\;Jones in every version this site writes; see the next section.

Escaping and line folding — where hand-written vCards break

Most import failures in a card you typed yourself are not “wrong property names.” They are an unescaped comma, a line that ran past 75 octets, or 2.1 quoted-printable that a 3.0 parser will not decode. The rules below are the ones this site's generator applies and the ones its parser undoes.

vCard 3.0 and 4.0 (RFC 2426 / RFC 6350) escape four characters inside text values, including the components of N and ADR:

A legal 3.0 card that actually needs three of those:

BEGIN:VCARD
VERSION:3.0
N:Smith\;Jones;Ann;;;
FN:Ann Smith\;Jones
ORG:Foo\, Inc.
NOTE:Line one\nLine two
END:VCARD

ORG:Foo, Inc. on a 3.0 card is wrong — the comma is a delimiter, so the company must be ORG:Foo\, Inc.. A parser unescapes in the opposite direction: \n (any case) back to a newline, then \,, \;, then \\. Structured values (N, ADR, ORG) are split on unescaped semicolons, so Smith\;Jones stays one family-name component.

vCard 2.1 does not play by that table. Inside structured components it escapes only the semicolon (\;); commas are literal. Newlines in an N component are flattened to a space. A 2.1 FN, ORG or NOTE that is plain ASCII is written as-is — ORG:Foo, Inc.is correct in 2.1 and incorrect in 3.0. The moment a 2.1 value has non-ASCII text or a newline, this site's generator switches that line to quoted-printable instead of backslash escapes.

Line folding is 75 octets, not 75 characters. RFC 2426 §2.6 and RFC 6350 §3.2: if a logical line is longer than 75 bytes of UTF-8, it is split. The first physical line may use 75 octets; each continuation is a CRLF, then a single space, then up to 74 octets of payload (the space already took one). Folding does not respect word boundaries — a generator will split onto as ont / o if that is where byte 75 falls:

NOTE:This note is long enough that a spec-compliant writer must fold it ont
 o a continuation line with a leading space.

The second physical line starts with a space. A parser that does not unfold will treat that space-prefixed line as garbage, or as a new property with no colon, and drop it. Tabs are accepted as a continuation indent as well as spaces. This site's generator unfolds both, then parses.

vCard 2.1 quoted-printable is a third folding dialect, used only on 2.1, and only when a value needs it (non-ASCII, or a newline in NOTE). The property line grows CHARSET=UTF-8 and ENCODING=QUOTED-PRINTABLE. Bytes outside printable ASCII, and the = character itself, become =XX hex: María is Mar=C3=ADa (UTF-8 C3 AD for í). A newline in NOTE becomes =0A. A semicolon that must survive inside a QP-encoded N or ADR component is =3B, so it cannot be mistaken for a slot separator.

A real 2.1 N/FN pair from this site's generator:

N;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:Garc=C3=ADa;Mar=C3=ADa;;;
FN;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:Mar=C3=ADa Garc=C3=ADa

Soft line breaks in quoted-printable are not the 75-octet space-fold. The physical line ends with =, and the next line continues without a leading space — and the writer will not split in the middle of an =XX escape. An unfolded example from this generator: NOTE;CHARSET=UTF-8;ENCODING=QUOTED-PRINTABLE:Esta es una nota bastante lar= then the next physical line starts at ga con tildes…. A 3.0 parser that only knows space-folding will leave those = signs in the value. CHARSET and quoted-printable belong on 2.1 cards only.

2.1 vs 3.0 vs 4.0 — the differences that actually bite

The VERSION line is not a comment. It selects a TYPE syntax, an escaping dialect, and whether FN is required. Writing 4.0 parameters under VERSION:3.0 — or 2.1 quoted-printable under 3.0 — is how a card that “looks fine in an editor” fails on iCloud.com. Same recommendation as the rest of this site: default 3.0, 2.1 for old devices, 4.0 when a CRM asks. The table is the part that bites when you ignore that.

The TYPE mismatch is the one that shows up in the wild most often. A 2.1 exporter writes TEL;CELL:. A 3.0 importer that only looks for TYPE=CELL will keep the number and drop the type — or, if it is strict, drop the line. A 4.0 card with TYPE=cell and a tel:+1… URI, fed to a 3.0-only importer, can land as the literal string tel:+1…in the phone field. This site's parser accepts bare CELL, TYPE=CELL, TYPE=cell, and MOBILE, and strips a leading tel: — that is defensive reading, not a license to mix dialects on the way out.

Group prefixes such as item1.TEL are an iCloud habit, not a version feature. They are legal on 3.0. A parser that does not strip the group will look up a property named ITEM1.TELand miss the number. This site's parser strips through the first dot before matching TEL, EMAIL and the rest.

Validate by round-tripping

A vCard that looks right in an editor can still be illegal: a missing FN, a comma that was not escaped, a fold that used two spaces, a 4.0 TYPE on a 3.0 VERSION. The cheapest check is to run the card through a parser you did not write and look at the fields it actually produced.

• One card, or a handful you just typed. Drop the .vcf on Open a VCF file. The viewer unfolds, decodes 2.1 quoted-printable, strips item1. prefixes and tel: URIs, and shows name / phones / emails / address as fields. If FN is empty, N did not split, or a number vanished, the card is the problem, not the phone.
• A dump of hundreds. Convert with VCF to CSV and read the table. First name, last name, two phones with types, two emails, company, title and the address parts should sit in their own columns. A column that is blank for everyone is usually a TYPE or escaping mismatch, not missing source data.
• You want a file a phone will import. Do not hand-finish the escaping and the 75-octet folds. Put the rows in a spreadsheet and use the CSV to VCF converter on the homepage. Pick 3.0 unless you have a concrete 2.1 device or a CRM that asked for 4.0. The generator writes CRLF, folds at 75 octets, escapes 3.0/4.0 values, and emits CHARSET + quoted-printable only on 2.1.

Round-tripping through a spreadsheet is lossy on purpose: PHOTO, UID, REV, extra TEL lines past the first two, and unknown properties do not survive a parse-and-regenerate. If you only need to concatenate files and keep every original line, that is Merge VCF files, which does not rewrite the card text at all.

vCard format — FAQ

• What standard is the vCard format? Which RFCs?

  Three documents, not one. vCard 2.1 is the Versit/IMC specification — it is not an IETF RFC. vCard 3.0 is RFC 2426. vCard 4.0 is RFC 6350. The internet media type is text/vcard. When software says it “speaks vCard,” it is speaking one of those three dialects; the VERSION line on each card tells you which.

• What is the relationship between a .vcf file and the vCard format?

  They are the same thing. vCard is the format name; .vcf is the usual filename extension (you will also see .vcard). A file named contacts.vcf is a vCard file: one or more BEGIN:VCARD…END:VCARD blocks of plain text. The MIME type is text/vcard. None of those names imply a particular version — look at the VERSION line inside each card.

• What is the difference between N and FN?

  N is the structured name: Family;Given;Middle;Prefix;Suffix. Empty slots stay empty; the semicolons still have to be there so the five parts line up. FN is the formatted display name — the string a phone actually shows in the list. vCard 3.0 (RFC 2426) and 4.0 (RFC 6350) require FN; 2.1 recommends it. If they disagree, FN wins on the screen and N wins when you sort by last name. Well-behaved writers emit both.

• Why does my hand-written VCF fail to import?

  Three pits, in the order they actually bite. (1) Escaping: in 3.0 and 4.0 a literal comma, semicolon, backslash or newline inside a value must be written as \, \; \\ or \n — a company named Foo, Inc. is ORG:Foo\, Inc., not ORG:Foo, Inc. (2) Folding: a physical line longer than 75 octets must be broken, with the continuation starting with a single space. (3) Missing FN: 3.0 and 4.0 require it; a card that only has N is not a valid 3.0/4.0 card. Drop the file on the Open VCF viewer on this site to see what a parser actually reads.

• How do I write the TYPE parameter so it actually imports?

  Match the VERSION. vCard 2.1 writes a bare type token: TEL;CELL:+14155550123. vCard 3.0 writes the TYPE= keyword in uppercase: TEL;TYPE=CELL:+14155550123. vCard 4.0 writes TYPE= in lowercase: TEL;TYPE=cell:+14155550123. This site's parser accepts all three, plus MOBILE as a synonym for CELL. If you need one file that Google Contacts, iCloud and Android will swallow, write 3.0 with TYPE=CELL / TYPE=WORK / TYPE=HOME.

• How long can a vCard line be?

  75 octets — bytes, not characters. A UTF-8 é is two octets, so a line of accented text hits the limit sooner than it looks. RFC 2426 §2.6 and RFC 6350 §3.2 fold by inserting CRLF plus a single space; the continuation then has 74 octets of payload. vCard 2.1 quoted-printable uses a different fold: a trailing = and the next line is not indented. Unfold first, then parse.

• How is PHOTO stored in a vCard? Does this site keep it?

  PHOTO holds either a URL or, more commonly, inline image bytes (JPEG or PNG, usually base64-encoded and folded across many physical lines). The tools on this site that parse a card into fields — the viewer and VCF to CSV — skip PHOTO, and the converters that generate a new vCard from a spreadsheet do not write it. Only the merge tool keeps photos, because it concatenates the original card text instead of regenerating it. Round-tripping through a CSV drops the photo; that is the trade.

• Which vCard version should I write?

  Default to 3.0 — it is what Google Contacts and iCloud export, and the version that fails least often on Android, iPhone and Outlook. Use 2.1 only for old feature phones, SIM-management tools and some car head units (and be ready to emit CHARSET and quoted-printable). Use 4.0 when a modern CRM specifically asks for RFC 6350. Do not mix TYPE syntax across versions on the same card.