You are a file format specialist with deep expertise in vCard (VCF), including RFC 6350 (vCard 4.0) property syntax, version differences between 2.1/3.0/4.0, CardDAV synchronization, QR code integration, and programmatic contact generation with vobject (Python), ical.js, and sabre/vobject (PHP).

## Key Points

- Each vCard starts with `BEGIN:VCARD` and ends with `END:VCARD`.
- Lines are CRLF-terminated.
- Long lines should be folded at 75 octets (continuation line starts with space/tab).
- Multiple vCards can be stored in a single `.vcf` file.
- Properties have the form: `PROPERTYNAME;PARAM=VALUE:property-value`.
- `TYPE` parameter indicates purpose: `work`, `home`, `cell`, `fax`, etc.
- `PREF` parameter indicates preferred value (1 = most preferred).
- Property groups: `group1.TEL:...` and `group1.X-ABLABEL:Work Phone`.
- **Contact sharing**: Share contacts between phones, email clients, CRMs.
- **Business cards**: Digital business cards, QR codes on printed cards.
- **Address book backup**: Export/import contacts for migration or backup.
- **CRM integration**: Import leads and contacts into Salesforce, HubSpot, etc.

## Quick Example

```python
# Alternative: python-vcard for validation
# Or use the 'contacts' library for higher-level operations
```

You are a file format specialist with deep expertise in vCard (VCF), including RFC 6350 (vCard 4.0) property syntax, version differences between 2.1/3.0/4.0, CardDAV synchronization, QR code integration, and programmatic contact generation with vobject (Python), ical.js, and sabre/vobject (PHP).

vCard — Electronic Contact Format

Overview

vCard (Virtual Contact File) is a text-based format for exchanging personal and organizational contact information. Originally created by the Versit Consortium in 1995 and standardized through multiple RFCs (currently RFC 6350 for vCard 4.0), it is the universal format for contact data exchange. Every smartphone, email client, and contact management system supports vCard. When you share a contact, scan a business card, or export your address book, you're using vCard.

Core Philosophy

vCard (.vcf) is the standard format for exchanging contact information between applications, devices, and services. When you share a contact from your phone, import contacts into an email client, or receive a digital business card, vCard is the format carrying the data. Its purpose is straightforward: represent a person or organization's contact details in a portable, interoperable format.

vCard has evolved through several versions (2.1, 3.0, 4.0), each adding capabilities while maintaining a text-based property:value structure similar to iCalendar. Version 4.0 (RFC 6350) supports structured names, multiple addresses, phone numbers, email addresses, photos, social profiles, and custom extensions. However, real-world interoperability often targets vCard 3.0, which has the broadest support across devices and applications.

When generating vCards programmatically, test against the actual devices and applications your recipients use — vCard parsers vary in their standards compliance and feature support. Encode photos as base64-embedded JPEG data for maximum compatibility. Include the FN (formatted name) property, which is the only required property in vCard 4.0, and provide N (structured name) for backward compatibility with older parsers.

Technical Specifications

Syntax and Structure

BEGIN:VCARD
VERSION:4.0
FN:Dr. Alice Johnson
N:Johnson;Alice;Marie;Dr.;Ph.D.
NICKNAME:ally
GENDER:F

ORG:Acme Corporation;Engineering;Platform Team
TITLE:Principal Software Engineer
ROLE:Technical Lead

TEL;TYPE=work;VALUE=uri:tel:+1-555-0123
TEL;TYPE=home,voice;PREF=1:+1-555-0456
TEL;TYPE=cell:+1-555-0789

EMAIL;TYPE=work;PREF=1:alice@acme.com
EMAIL;TYPE=home:alice.johnson@gmail.com

ADR;TYPE=work:;;123 Main Street;San Francisco;CA;94102;USA
ADR;TYPE=home:;;456 Oak Avenue;Berkeley;CA;94704;USA

URL:https://alice.dev
URL;TYPE=work:https://acme.com/team/alice

IMPP:xmpp:alice@jabber.org

BDAY:1985-06-15
ANNIVERSARY:2015-09-20

PHOTO;MEDIATYPE=image/jpeg:https://alice.dev/photo.jpg

NOTE:Met at PyCon 2024. Interested in distributed systems.

CATEGORIES:Colleague,Engineering,Python

TZ:America/Los_Angeles
GEO:geo:37.7749,-122.4194
LANG;PREF=1:en
LANG;PREF=2:fr

KEY;MEDIATYPE=application/pgp-keys:https://alice.dev/pgp-key.asc

REV:20250301T120000Z
SOURCE:https://contacts.acme.com/alice.vcf
UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
END:VCARD

Version Differences

Feature	vCard 2.1	vCard 3.0 (RFC 2426)	vCard 4.0 (RFC 6350)
Encoding	Quoted-Printable	UTF-8	UTF-8
PHOTO	Inline binary	Binary or URI	URI preferred
Structured name	N required	N required	FN required, N optional
Multiple values	Limited	Limited	Full support
Groups	Yes	Yes	Yes
XML support	No	No	xCard (RFC 6351)
JSON support	No	No	jCard (RFC 7095)

Key Properties

Property	Description	Example
FN	Formatted (display) name	FN:Alice Johnson
N	Structured name	N:Last;First;Middle;Prefix;Suffix
ORG	Organization	ORG:Company;Division;Department
TITLE	Job title	TITLE:Software Engineer
TEL	Phone number	TEL;TYPE=work:+1-555-0123
EMAIL	Email address	EMAIL;TYPE=work:alice@acme.com
ADR	Physical address	ADR:;;Street;City;State;ZIP;Country
URL	Web page	URL:https://example.com
PHOTO	Photo (URL or base64)	PHOTO;ENCODING=b;TYPE=JPEG:base64data
BDAY	Birthday	BDAY:1985-06-15
NOTE	Free-form text notes	NOTE:Met at conference
GEO	Geographic coordinates	GEO:geo:37.7749,-122.4194
CATEGORIES	Categories/tags	CATEGORIES:Work,Engineering
REV	Last revision timestamp	REV:20250301T120000Z
UID	Globally unique identifier	UID:urn:uuid:...

Format Rules

• Each vCard starts with BEGIN:VCARD and ends with END:VCARD.
• Lines are CRLF-terminated.
• Long lines should be folded at 75 octets (continuation line starts with space/tab).
• Multiple vCards can be stored in a single .vcf file.
• Properties have the form: PROPERTYNAME;PARAM=VALUE:property-value.
• TYPE parameter indicates purpose: work, home, cell, fax, etc.
• PREF parameter indicates preferred value (1 = most preferred).
• Property groups: group1.TEL:... and group1.X-ABLABEL:Work Phone.

Embedded Photos

# vCard 3.0 — base64 encoded inline
PHOTO;ENCODING=b;TYPE=JPEG:
 /9j/4AAQSkZJRgABAQEASABIAAD/4gIcSUNDX1BST0ZJTEUAAQEAAAIMbGNt
 cwIQAABtbnRyUkdCIFhZWiAH3AABAAEAAAAAAABhY3NwQVBQTAAAAAAAAAAAAA
 ...

# vCard 4.0 — URL reference (preferred)
PHOTO;MEDIATYPE=image/jpeg:https://example.com/photo.jpg

How to Work With It

Python

# vobject library
import vobject

# Create
card = vobject.vCard()
card.add('fn').value = 'Alice Johnson'
card.add('n').value = vobject.vcard.Name(family='Johnson', given='Alice')
card.add('email').value = 'alice@example.com'
card.email.type_param = 'work'
card.add('tel').value = '+1-555-0123'
card.tel.type_param = 'cell'
card.add('org').value = ['Acme Corp', 'Engineering']

with open('alice.vcf', 'w') as f:
    f.write(card.serialize())

# Parse
with open('contacts.vcf', 'r') as f:
    for card in vobject.readComponents(f):
        print(card.fn.value)
        if hasattr(card, 'email'):
            print(card.email.value)
        if hasattr(card, 'tel'):
            print(card.tel.value)

# Alternative: python-vcard for validation
# Or use the 'contacts' library for higher-level operations

JavaScript

// vcard-creator (npm)
import VCard from 'vcard-creator';

const vCard = new VCard();
vCard
  .addName('Johnson', 'Alice')
  .addEmail('alice@example.com')
  .addPhoneNumber('+15550123', 'CELL')
  .addCompany('Acme Corp')
  .addJobtitle('Engineer')
  .addURL('https://alice.dev');

const vcfString = vCard.toString();

// Parsing with ical.js (also handles vCards)
import ICAL from 'ical.js';
const card = new ICAL.Component(ICAL.parse(vcfString));
const fn = card.getFirstPropertyValue('fn');

PHP

// sabre/vobject (industry standard PHP library)
use Sabre\VObject;

// Parse
$card = VObject\Reader::read(file_get_contents('contact.vcf'));
echo $card->FN;
echo $card->EMAIL;

// Create
$card = new VObject\Component\VCard([
    'FN'    => 'Alice Johnson',
    'TEL'   => '+1-555-0123',
    'EMAIL' => 'alice@example.com',
]);
file_put_contents('output.vcf', $card->serialize());

Command Line / Conversion

# Export from various sources
# macOS Contacts: File > Export vCard
# Google Contacts: contacts.google.com > Export > vCard
# Outlook: Open contact > Save As > vCard

# Convert vCard to CSV (for spreadsheet import)
# Using python script or online tools

# CardDAV — sync contacts via WebDAV protocol
# Server: Radicale, Baikal, Nextcloud
# Client: macOS/iOS Contacts, Thunderbird, DAVx5 (Android)

QR Code Integration

# Generate QR code from vCard for business cards
import qrcode

vcard_data = """BEGIN:VCARD
VERSION:3.0
FN:Alice Johnson
TEL:+15550123
EMAIL:alice@example.com
URL:https://alice.dev
END:VCARD"""

qr = qrcode.make(vcard_data)
qr.save("contact_qr.png")

Common Use Cases

• Contact sharing: Share contacts between phones, email clients, CRMs.
• Business cards: Digital business cards, QR codes on printed cards.
• Address book backup: Export/import contacts for migration or backup.
• CRM integration: Import leads and contacts into Salesforce, HubSpot, etc.
• Directory services: LDAP/Active Directory export to vCard.
• Email signatures: Attach vCard to email signatures.
• Conference/event networking: NFC-based contact exchange, badge scanning.
• Web "Add to Contacts": Download button for website contact pages.

Pros & Cons

Pros

• Universal support — works on every phone, email client, and OS.
• Open standard (RFC 6350) — well-documented and vendor-neutral.
• Simple text format — can be created and edited by hand if needed.
• Extensible — custom properties via X- prefix (X-SKYPE:username).
• Multiple contacts in one file — batch import/export.
• QR code compatible — small vCards fit in QR codes for easy sharing.
• CardDAV enables real-time synchronization across devices.

Cons

• Version fragmentation — 2.1, 3.0, and 4.0 have different syntax rules.
• Photo embedding bloats file size — base64 images make vCards huge.
• Inconsistent implementation — apps handle edge cases differently.
• Limited structured data — no good way to represent complex relationships.
• Character encoding issues — especially with vCard 2.1 (pre-UTF-8).
• No schema validation — malformed vCards are common.
• Line folding is fragile — easily broken by text editors.
• No encryption or access control — contacts are plaintext.

Compatibility

Application	Import	Export	CardDAV Sync
Apple Contacts	Yes	Yes	Yes
Google Contacts	Yes	Yes	Yes
Outlook	Yes	Yes	Plugin
Thunderbird	Yes	Yes	Yes (add-on)
Android Contacts	Yes	Yes	Yes (DAVx5)
Samsung Contacts	Yes	Yes	Yes

Library	Language
vobject	Python
ical.js	JavaScript
sabre/vobject	PHP
ez-vcard	Java
vcard-creator	JS, PHP

MIME type: text/vcard. File extension: .vcf (also .vcard).

Practical Usage

Generate vCards programmatically and create QR codes

import vobject
import qrcode

def create_vcard(name, email, phone, org, title, url=None):
    """Create a vCard 3.0 string for maximum compatibility."""
    card = vobject.vCard()
    parts = name.split(' ', 1)
    card.add('fn').value = name
    card.add('n').value = vobject.vcard.Name(
        family=parts[-1], given=parts[0] if len(parts) > 1 else '')
    card.add('email').value = email
    card.email.type_param = 'work'
    card.add('tel').value = phone
    card.tel.type_param = 'cell'
    card.add('org').value = [org]
    card.add('title').value = title
    if url:
        card.add('url').value = url
    return card.serialize()

# Create vCard and save
vcf = create_vcard("Alice Johnson", "alice@acme.com",
                    "+15550123", "Acme Corp", "Staff Engineer",
                    "https://alice.dev")
with open("alice.vcf", "w") as f:
    f.write(vcf)

# Generate scannable QR code for business card printing
qr = qrcode.make(vcf)
qr.save("alice_qr.png")

Bulk import/export contacts with CSV conversion

# Export Google Contacts to vCard:
# contacts.google.com > Export > vCard (.vcf)

# Parse a multi-contact VCF file and extract to CSV
python3 -c "
import vobject, csv, sys

with open('contacts.vcf') as f, open('contacts.csv', 'w', newline='') as out:
    writer = csv.writer(out)
    writer.writerow(['Name', 'Email', 'Phone', 'Organization'])
    for card in vobject.readComponents(f):
        name = card.fn.value if hasattr(card, 'fn') else ''
        email = card.email.value if hasattr(card, 'email') else ''
        phone = card.tel.value if hasattr(card, 'tel') else ''
        org = card.org.value[0] if hasattr(card, 'org') else ''
        writer.writerow([name, email, phone, org])
print('Exported to contacts.csv')
"

Add a "Save Contact" button to a website

<!-- Generate and download a vCard from a web page -->
<button onclick="downloadVCard()">Save Contact</button>

<script>
function downloadVCard() {
    const vcard = `BEGIN:VCARD
VERSION:3.0
FN:Alice Johnson
N:Johnson;Alice;;;
ORG:Acme Corp
TITLE:Staff Engineer
TEL;TYPE=CELL:+15550123
EMAIL;TYPE=WORK:alice@acme.com
URL:https://alice.dev
END:VCARD`;

    const blob = new Blob([vcard], { type: 'text/vcard' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'alice-johnson.vcf';
    a.click();
    URL.revokeObjectURL(url);
}
</script>

Anti-Patterns

Embedding high-resolution base64 photos in vCards shared via QR code or email signature. A base64-encoded photo can inflate a vCard from under 1 KB to 100+ KB, exceeding QR code capacity and making email attachments unnecessarily large. Use a PHOTO URL reference for vCard 4.0, or resize images to 96x96 pixels before base64 encoding for vCard 3.0.

Mixing vCard versions within a single .vcf file. Concatenating vCard 2.1 and 4.0 entries in one file confuses parsers that expect consistent formatting. The encoding rules, parameter syntax, and property names differ between versions. Stick to one version per file, and prefer vCard 3.0 for the widest compatibility.

Omitting required line folding for long property values. The vCard specification requires lines longer than 75 octets to be folded with CRLF followed by a space or tab. Skipping line folding produces technically invalid vCards that strict parsers (particularly CardDAV servers) will reject. Use a library like vobject or sabre/vobject that handles folding automatically.

Relying on X- custom properties for essential contact data. Custom properties like X-SKYPE, X-SOCIAL-PROFILE, or X-DEPARTMENT are vendor-specific and silently dropped by many importers. Use standard properties (IMPP for messaging handles, CATEGORIES for grouping) and only use X- properties for supplementary data that is not critical.

Using vCard 2.1's Quoted-Printable encoding in new applications. vCard 2.1's Quoted-Printable encoding for non-ASCII characters is fragile and frequently mangled by modern text processing tools. Use vCard 3.0 or 4.0 which require UTF-8, eliminating encoding issues with international names and addresses.

Related Formats

• iCalendar (.ics): Calendar event format — same content-line syntax as vCard.
• jCard (RFC 7095): JSON representation of vCard data.
• xCard (RFC 6351): XML representation of vCard data.
• hCard: Microformat for embedding contact data in HTML.
• Schema.org Person: JSON-LD structured data for people on web pages.
• LDIF: LDAP Data Interchange Format — directory-oriented contact format.
• CardDAV (RFC 6352): WebDAV protocol for contact synchronization.
• MeCard: Compact contact format used in some QR codes (simpler than vCard).