CorrectVCF

✅ My .vcf File Won't Import — Quick Checklist for Developers

A fast, practical list for engineers exporting vCard files from their application.

If your .vcf file isn’t importing into Google Contacts, iOS, Outlook, Android, or your CRM, walk through this checklist first. These are the most common reasons vCard imports fail.

  1. The file has the correct extension and MIME type

The file must end in .vcf.

When serving the file, use one of these MIME types:

text/vcard

text/x-vcard

Incorrect MIME types (e.g., application/octet-stream) can cause downloads to break on some devices.

  1. The vCard has a valid start and end

Every vCard must wrap its content between these two lines:

BEGIN:VCARD … END:VCARD

If either is missing, many clients won’t import the file.

  1. You declared a supported vCard version

Include exactly one version line:

VERSION:3.0

or

VERSION:4.0

Common failure modes:

Missing VERSION entirely

Using deprecated 2.1 without proper encoding rules

Including multiple conflicting version lines

  1. The vCard includes at least one name field

Most clients require a minimum identity:

FN:Jane Doe

Optionally, include the structured name:

N:Doe;Jane;;;

Empty FN: or missing both fields will often cause import errors.

  1. Lines are properly encoded and escaped

vCard is strict about special characters:

Commas inside fields must be escaped: ,

Semicolons must be escaped: ;

Line breaks inside fields must be written as \n

Long lines should follow spec-compliant “folding” if you generate them (though most modern clients tolerate long lines)

If the text contains characters outside ASCII, make sure the file encoding is UTF-8.

  1. Fields follow the correct syntax

Examples of well-formed properties:

TEL;TYPE=cell:+1-555-123-4567 EMAIL;TYPE=work:[email protected] ADR;TYPE=home:;;123 Main St;Austin;TX;78701;USA

Avoid:

Missing colons

Using commas instead of semicolons in ADR

Omitting required components

Non-standard parameter names

  1. Include a UID if your app supports syncing

Not required, but strongly recommended:

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

Without a UID, re-imports may create duplicates rather than updating existing contacts.

  1. Multi-contact exports need correct boundaries

If your export contains multiple contacts, each must be fully wrapped:

BEGIN:VCARD VERSION:3.0 FN:Jane Doe END:VCARD BEGIN:VCARD VERSION:3.0 FN:John Smith END:VCARD

Never merge two contacts inside one BEGIN/END block.

  1. Test import with at least two major clients

At a minimum, test with:

Google Contacts

iOS / macOS Contacts

For extra safety, also test:

Outlook

Android (native Contacts app)

Popular CRMs (HubSpot, Salesforce, Zoho)

Each client has slightly different tolerances — a file that works in one may fail in another.

Minimal valid example

Here’s the shortest valid vCard most clients will accept:

BEGIN:VCARD VERSION:3.0 FN:Jane Doe N:Doe;Jane;;; EMAIL:[email protected] END:VCARD

Still having trouble?

Upload your file to CorrectVCF and we’ll validate, normalize, and repair it automatically — no spec-reading required.