vCard Files, Explained
After reading this you can read a .vcf file byte by byte, understand why commas and semicolons behave differently, and generate a contact file that imports cleanly into every mainstream phone and mail app.
A vCard is a plain-text file that describes one or more contacts. The extension is .vcf. When someone sends you a contact by email or AirDrop, that attachment is almost always a vCard. Open it in a text editor and you see readable lines, not binary noise.
Here is a complete, valid vCard for one person:
BEGIN:VCARD
VERSION:3.0
N:Doe;Jane;;;
FN:Jane Doe
ORG:ABC Tools
TEL;TYPE=CELL:+1-555-0142
EMAIL;TYPE=INTERNET:[email protected]
END:VCARD
Seven meaningful lines. Every contact starts with BEGIN:VCARD and ends with END:VCARD. Everything between is a set of properties, one per line, each with a name, optional parameters, and a value after the colon.
What a vCard is and when to use it
The format is defined by RFC 6350 for version 4.0, and by RFC 2426 for version 3.0. The structure is the same in both: property lines wrapped in a BEGIN/END pair. Only the property syntax and the allowed versions differ.
Reach for a vCard when you need to move contact data between systems that you do not control. Exporting your phone's address book, attaching a business card to an email signature, or handing a list of 200 people to a CRM all fit. The file is text, so you can inspect it, edit it in any editor, and store it in version control.
If you need contacts for testing rather than real people, generate them with the Test data generator first, then paste the fields here. That keeps real personal data out of test files.
Do not use a vCard for calendar events, tasks, or availability. Those belong in iCalendar (.ics) files, which have their own property set. See the iCalendar generator & parser for that side of the standard.
Why version 3.0 is the default
Three versions exist in the wild: 2.1, 3.0, and 4.0. Version 4.0 is the newest and cleanest, but adoption is uneven. Some older mail clients and phone import routines still choke on 4.0 properties.
Version 3.0 is the safe middle. Every phone and mail app in current use imports it. That is why this tool writes VERSION:3.0. The visible cost is small: 3.0 requires the N and FN properties, and it uses TYPE=CELL where 4.0 would write TYPE=cell. The gain is that the file works everywhere.
The grammar of a property line
Every content line has the same shape. Read it as three parts separated by a colon and semicolons:
The NAME is the property, such as TEL or EMAIL. Each optional PARAM=value is separated by a semicolon and refines the property, for example TYPE=CELL. The colon marks the boundary between metadata and data. Everything after the colon is the value.
Two structural characters matter inside values. A semicolon separates the fields of a structured value. A comma separates repeated items within one field. The N property is the clearest example. Its value has exactly five fields in a fixed order:
So N:Doe;Jane;;; means family name Doe, given name Jane, and three empty fields for middle name, prefix, and suffix. The empty fields still need their semicolons. Dropping them changes the meaning.
Escaping: the part that breaks silently
Because comma, semicolon, backslash, and newline all carry structural meaning, a literal one inside a value must be escaped with a backslash. RFC 6350 defines four escapes:
| Literal character | Written as | Reason |
|---|---|---|
comma , | \, | separates repeated items |
semicolon ; | \; | separates structured fields |
backslash \ | \\ | the escape character itself |
| newline | \n | ends a property line |
Consider a company named Smith, Jones & Co. Written raw as ORG:Smith, Jones & Co, a strict parser reads two organization units: Smith and Jones & Co. Written correctly as ORG:Smith\, Jones & Co, it stays one value. A street address with a line break must use \n, not a real newline, because a real newline would end the property.
The classic failure is a comma in a company name or a semicolon in a job title. Import succeeds, no error appears, but the field is silently split. Always check the parsed table after import rather than trusting that a green checkmark means correct data.
Line folding for long values
The specification limits a physical line to 75 octets. Longer values are folded: split across lines, with each continuation line starting with a single space or tab. A parser rebuilds the value by removing that leading whitespace and the preceding line break.
A note of 90 characters becomes two physical lines. The first holds NOTE: plus 69 characters (75 octets total), and the second begins with one space followed by the remaining 21 characters. When you inspect a folded file by eye, join any line that starts with whitespace to the line above it before reading the value.
A worked example you can reproduce
Building the demo contact
Load the demo data and press generate. The form defaults describe Jane Doe at ABC Tools. Here is how each field becomes a property line.
- The name splits into
N:Doe;Jane;;;(structured) andFN:Jane Doe(the display name). Both are required in 3.0. - The organization becomes
ORG:ABC Tools. No comma, so no escaping. - The mobile number becomes
TEL;TYPE=CELL:+1-555-0142. TheTYPEparameter sits before the colon. - The email becomes
EMAIL;TYPE=INTERNET:[email protected]. - The whole block is wrapped in
BEGIN:VCARD,VERSION:3.0, andEND:VCARD.
Count the octets. The file is 7 content lines plus the two structural lines and the version line, 10 lines in total. No value exceeds 75 octets, so nothing is folded. Save it as jane.vcf and it imports as one contact.
Reading a multi-contact file
One .vcf file can hold many contacts. Each is its own BEGIN:VCARD to END:VCARD block, stacked one after another with no separator between them. A file with 3 contacts has 3 BEGIN:VCARD lines and 3 matching END:VCARD lines.
When you paste such a file into the parser, it splits on those boundaries and shows one row per contact. The chart below shows how file size grows with contact count for the demo-sized card of roughly 180 bytes each.
Because the growth is linear, a large export is never surprising. A 90 KB file is 500 people, not a corrupt blob. If a parser reports fewer contacts than you expected, look for a missing END:VCARD, which merges two blocks into one.
Common mistakes
- Missing
FN - Version 3.0 requires the formatted name. Some apps hide contacts without it. Always include
FNeven when you haveN. - Wrong field order in
N - The order is family, given, additional, prefix, suffix. Swapping the first two produces contacts filed under the wrong name.
- Real newlines inside a value
- A multi-line address needs
\n, not a pressed Enter key. A literal newline ends the property early. - Unescaped commas in
ORGorADR - The silent split. Check the parsed table.
- Wrong encoding
- Save as UTF-8. Accented names in Latin-1 or Windows-1252 arrive as garbled characters on other systems.
Related tools
To visualise how many contacts came from each source or organization, export counts and paste them into the Chart maker for a quick bar chart. For calendar data rather than contacts, use the iCalendar generator linked above. For synthetic contacts to test an import pipeline, use the test data generator linked above.
Frequently asked questions
Why does my contact import twice?
Your file probably has two BEGIN:VCARD blocks with the same person, or an editor duplicated the block. Count the BEGIN:VCARD lines: that number equals the number of contacts the parser will create.
Can one vCard hold two phone numbers?
Yes. Add a second TEL line with a different TYPE, for example TEL;TYPE=WORK:+1-555-0100 below the cell line. The same applies to EMAIL and ADR.
Does the data leave my browser?
No. Generating and parsing both run entirely on your device. The .vcf file and its contents are never uploaded.
Should I use version 3.0 or 4.0?
Use 3.0 for maximum compatibility, which is what this tool writes. Choose 4.0 only when every system in your workflow is known to support it, since 4.0 adds properties older apps ignore or reject.
Why are there five semicolons in the name line?
The N property always carries five fields separated by semicolons, even when some are empty. The empty fields hold the middle name, prefix, and suffix positions so parsers read the value correctly.
Related tools
JSON → Types Generator
Generate TypeScript, Python or Go types from JSON.
Test Data Generator
Fake names, emails, addresses — CSV or JSON datasets.
XML Formatter & Validator
Pretty-print, minify and validate XML.
iCalendar Generator & Parser
Create .ics event files and inspect existing ones.
Auto Analyst: Instant Statistical Report
Drop a CSV or Excel file and get a statistician’s report: data problems, distributions, every real relationship, key drivers and Simpson’s paradox warnings, in plain English.
CSV Viewer & Editor
View, edit, sort, filter and extract columns from CSV files.