Which vCard version should I generate?

vCard 3.0 is the safest default for cross-platform imports (Google, iOS/iCloud, Android, Outlook).

How do I prevent import failures?

Use UTF-8 (without BOM), correct line endings, include required fields like FN and N, and validate your output.

How do I catch issues before users import?

Validate generated .vcf files in CI or upload a sample to CorrectVCF to see exact importer-facing problems.

Generate Valid vCard (.vcf) Files (Templates + Rules)

Before shipping, validate your output: try CorrectVCF.

The vCard format is deceptively simple. It’s just a text file with a handful of fields… until it isn’t.

Maybe you’ve experienced this already: your app generates a .vcf file that looks valid — it even works in one contact manager — but then Gmail rejects it, or iOS silently drops parts of it, or Outlook decides to strip everything except the name.

This guide walks developers through best practices for generating vCard files that work consistently across platforms, using modern conventions and avoiding the subtle traps that cause import failures. Whether you’re exporting contact data from a CRM, building a sync feature, or generating downloadable .vcf cards for your users, these patterns will save you hours of debugging.

1. Choose the right vCard version (hint: it’s probably 3.0)

Before writing a single field, decide which vCard version to generate.

vCard 2.1
- Extremely old; common in legacy systems and older devices
- Supports non-UTF-8 encodings
- Highly inconsistent parameter rules
- Only recommended if you explicitly support legacy corporate systems or old devices
vCard 3.0
- The de facto universal standard
- Supported by Google Contacts, iCloud, iOS/macOS, Android, Outlook, and most CRMs
- UTF-8 compatible and has stable import behavior
- Recommended for most applications
vCard 4.0
- The current official IETF standard
- Better structured value types and multi-value fields
- Weak support in Microsoft products and some Android contact managers

Best practice recommendation

Unless your user base requires otherwise, ship vCard 3.0:

VERSION:3.0

vCard 3.0 strikes the safest balance between capability, practicality, and interoperability.

2. Always include both `FN` and `N` fields (even if they’re redundant)

Many generators output only FN: (display name) or only N: (structured components). Both choices lead to platform quirks.

Why both are needed:

Google Contacts uses FN as the display name
iOS/macOS rely heavily on N for component parsing
Outlook uses both in different contexts
CRMs often split fields based on N

Best practice:

FN:Jane Doe
N:Doe;Jane;;;

Even if you don’t have all the name components (prefix, suffix), include the correct number of semicolons to maintain structure.

3. Normalize character encoding (UTF-8 everything)

Many vCard import problems come from encoding inconsistencies. The fix:

Always output UTF-8
Avoid mixing line endings from different OS environments
Escape special characters properly (\,, \;, \n)

If you’re serving vCards over HTTP, make UTF-8 explicit:

Content-Type: text/vcard; charset=utf-8

4. Format phone numbers, emails, and URLs with `TYPE=` parameters

Contacts without type metadata often import incorrectly or get collapsed into the wrong buckets.

The wrong way:

TEL:5551234567
EMAIL:[email protected]

The right way:

TEL;TYPE=cell:+1-555-123-4567
EMAIL;TYPE=work:[email protected]
URL;TYPE=homepage:https://www.example.com

Why this matters:

iOS decides where to display the number based on TYPE
Outlook may strip phone numbers without types in some cases
CRMs may categorize all emails as “other” without a type
Google Contacts adds inconsistent defaults unless you specify one

5. Don’t forget the `UID` (it prevents duplicate contacts)

If your users ever re-import contacts, sync between multiple apps, or perform bulk updates, a missing UID almost guarantees duplicates.

Best practice:

UID:123e4567-e89b-12d3-a456-426614174000

Why it matters:

Google Contacts uses UID for deduplication
iOS uses it for updates via .vcf re-imports
CRMs rely on it heavily to detect changes

6. Dates must follow the vCard date format

For birthdays, anniversaries, and other dates, vCard syntax is strict:

YYYY-MM-DD

Best practice example:

BDAY:1985-04-23

If you provide human-formatted dates (e.g., 04/23/1985), iOS may skip them and Outlook may insert the wrong year.

7. Address fields are semicolon-delimited (never comma-delimited)

Correct format:

ADR;TYPE=home:;;123 Main St;Austin;TX;78701;USA

The seven positional fields are:

PO Box
Extended address
Street
City
State
Postal code
Country

Even if you don’t have all seven, preserve structure.

Common mistake:

ADR:123 Main St, Austin, TX 78701, USA

This will break in Google Contacts and many CRMs.

8. Photo embedding should use Base64 or hosted links properly

If you embed photos incorrectly, you’ll either inflate file size or cause import failures. Two valid methods:

Option A: Embedded Base64

PHOTO;ENCODING=b;TYPE=JPEG:/9j/4AAQSkZJRgABAQAAAQABAAD...

Pros: self-contained
Cons: large file size; some clients reject unusually large vCards

Option B: External URL

PHOTO;VALUE=URI:https://example.com/photos/jane.jpg

Pros: smaller file size; faster generation; supports dynamic updates
Cons: some offline imports won’t fetch the image

Best practice: if the file exceeds ~500 KB, prefer external URLs.

9. Multi-contact files must have properly delimited blocks

If you’re exporting multiple contacts inside a single .vcf, every contact needs a complete wrapper:

BEGIN:VCARD
...
END:VCARD
BEGIN:VCARD
...
END:VCARD

Common mistakes that break imports:

Leaving out END:VCARD before the next contact
Including multiple VERSION fields outside contact blocks
Nesting contacts (some CRMs do this)

Best practice: treat each contact as fully independent.

10. Don’t include empty properties

Empty fields are allowed but discouraged. Example of what not to do:

TEL:
EMAIL:
ADR;TYPE=home:;;;;;;

These produce odd behavior across clients, and may cause Google Contacts to silently drop a field block. Only write fields that contain data.

11. Deduplicate before exporting

Before writing a .vcf, normalize and dedupe:

Phone numbers (strip formatting)
Email addresses (case-normalize)
URLs (strip trailing slashes)
Addresses (normalize whitespace)
Custom fields or notes

Deduping before writing results in cleaner, smaller files and prevents confusion during import.

12. Test your output with multiple importers (not just one)

Every platform has its own quirks. A vCard that works in iOS may not work in Google Contacts, and vice-versa.

Minimum testing suite:

Google Contacts
iOS/macOS Contacts
Outlook (desktop + web)
At least one CRM (HubSpot, Salesforce, or Zoho)

Bonus: test on Android (OEM apps sometimes differ).

13. Use tools to validate your output (or automate it)

Manually eyeballing .vcf files is painful. A validator saves hours and catches mistakes you won’t see.

CorrectVCF can:

Parse, validate, and lint .vcf files
Normalize formatting
Repair malformed content
Standardize encoding
Auto-fix common errors
Clean up duplicates
Identify fields incompatible with certain importers

Developers should automate validation in CI or during export routines.

14. Provide both download and copy-to-clipboard options

If you’re providing vCards through UI, consider offering:

A downloadable .vcf file
A “Copy raw vCard” button
API access for backend automation

This improves developer experience and enables integrations.

15. Keep your output predictable and minimal

The more fields you add, the more likely one importer is going to dislike something. Include only the essentials unless your use case requires additional attributes.

Suggested minimal safe set:

BEGIN:VCARD
VERSION:3.0
FN:Jane Doe
N:Doe;Jane;;;
TEL;TYPE=cell:+1-555-123-4567
EMAIL;TYPE=work:[email protected]
UID:123e4567-e89b-12d3-a456-426614174000
END:VCARD

If you add extras (photo, org, title, address, anniversary, URLs, custom fields), validate them thoroughly.

16. Document your export logic for future developers

Most vCard bugs come from tribal knowledge disappearing. Document:

How you generate each field
Which version you follow
How you escape characters
How you encode the file
Which clients you support
Any known limitations or quirks

This prevents regressions in future updates.

Final Thoughts

The vCard format is simple on the surface, but real-world interoperability requires precision. With consistent encoding, correct field structure, proper type metadata, stable UIDs, well-formed addresses, and multi-client testing, your exports stay predictable and compatible with major importers.

If you’re generating vCards at scale, or want an automated way to audit your output, CorrectVCF is built exactly for that — validation, repair, and normalization with developer-friendly tooling.

Fix your .vcf file in seconds

Upload a vCard and get a clean, import-ready file for Google Contacts, Outlook, iPhone, Android, and CRMs.

Try the CorrectVCF Autofix Tool Back to Help