Converting VCF contacts to JSON is essential for developers integrating contact data into web applications, REST APIs, databases, or JavaScript-based frontends. While JSON is the standard data interchange format for modern software, VCF (vCard) is the standard for contact sharing. Bridging these two formats lets you import address book data into any system that reads JSON.
However, the conversion is not a simple file rename. VCF uses a property-based text format (one property per line, with TYPE parameters and special encoding), while JSON uses nested key-value pairs. Because of these structural differences, how you structure the JSON output (flat objects vs jCard arrays) depends on your downstream use case. If you need a tabular format instead, see our VCF to CSV or VCF to Excel guides.
We have built VCF parsing and conversion tools at Univik since 2013 and handle JSON export workflows for developers building CRM integrations, contact APIs, and migration scripts. This guide covers four methods to use a VCF to JSON converter, from a Python script you can customize to online tools that require no code.
Two JSON Formats for vCard Data
Before converting, decide which JSON structure fits your use case. There are two common approaches, and choosing the right one first saves you from reformatting later.
Flat JSON (Recommended for Most Uses)
Each contact becomes a JSON object with simple key-value pairs like “firstName”, “lastName”, “email”, “phone.” This is the format most APIs and databases expect. It is easy to read, easy to query, and maps directly to database columns or form fields. Use this format unless you have a specific reason to use jCard.
Example:
{"firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "phone": "+1-555-0123"}
jCard (RFC 7095, Standards-Compliant)
jCard is an IETF standard (RFC 7095) that represents vCard data as JSON arrays. It preserves every vCard property, parameter, and value type with full round-trip fidelity. The format is verbose and harder to read, but it is the correct choice if you need to convert JSON back to VCF without data loss, or if you are building a CardDAV-compatible system.
Example:
["vcard", [["version", {}, "text", "3.0"], ["fn", {}, "text", "Jane Doe"]]]
4 Methods to Convert VCF to JSON
Method 1: Python Script (Cross-Platform, Customizable)
Python is the most flexible option because you control the JSON schema entirely. The vobject library parses VCF files and gives you access to every vCard property, so you can build exactly the JSON structure your application needs.
1
Install the vobject library: pip install vobject
2
Save the following as vcf_to_json.py:
import vobject, json, sys
vcf_file = sys.argv[1] if len(sys.argv) > 1 else "contacts.vcf"
with open(vcf_file, "r", encoding="utf-8") as f:
  vcf_data = f.read()
contacts = []
for card in vobject.readComponents(vcf_data):
  c = {}
  if hasattr(card, "fn"): c["fullName"] = card.fn.value
  if hasattr(card, "n"):
    c["firstName"] = card.n.value.given
    c["lastName"] = card.n.value.family
  if hasattr(card, "email"): c["email"] = card.email.value
  if hasattr(card, "tel"): c["phone"] = card.tel.value
  if hasattr(card, "org"):
    c["organization"] = card.org.value[0]
  if hasattr(card, "title"): c["title"] = card.title.value
  contacts.append(c)
with open("contacts.json", "w", encoding="utf-8") as f:
  json.dump(contacts, f, indent=2, ensure_ascii=False)
print(f"Converted {len(contacts)} contacts to contacts.json")
3
Run it: python vcf_to_json.py contacts.vcf
The output is a JSON array of contact objects. Customize the script by adding more properties (URL, NOTE, BDAY, ADR) or changing the key names to match your API schema.
Method 2: Node.js with vcard-json (For JavaScript Projects)
If your project is already JavaScript-based, then the vcard-json npm package parses VCF files directly in Node.js without needing Python.
1
Install the package: npm install vcard-json
2
Create convert.js:
const vcard = require("vcard-json");
const fs = require("fs");
vcard.parseVcardFile("contacts.vcf", (err, data) => {
  if (err) return console.error(err);
  fs.writeFileSync("contacts.json",
    JSON.stringify(data, null, 2));
  console.log(data.length + " contacts converted");
});
3
Run it: node convert.js
The vcard-json library outputs a JSON array with fullname, email, phone, and other fields. It supports vCard 2.1 and 3.0.
Method 3: Online VCF to JSON Converter (No Code)
If you do not want to write code, then online converters handle the parsing for you. Upload a VCF file, get a JSON file back.
1
Go to an online VCF to JSON converter. ConversionTab (conversiontab.com/vcf/json) processes files locally in the browser. Aconvert (aconvert.com) processes files server-side.
2
Upload your VCF file or paste vCard text. Some tools accept both file upload and direct text input for single contacts.
3
Download the JSON output. Copy the result or download as a .json file. Browser-based tools that process locally (like ConversionTab) are safer for sensitive contact data because the file never leaves your device.
Method 4: VCF Converter Tool (GUI, Bulk Files, No Coding)
A dedicated VCF converter tool provides a graphical interface for converting VCF files to JSON. Load files, preview contacts, select fields, and export to JSON. This is the simplest option for non-developers who need bulk conversion.
1
Load VCF files. Use Add Files or Add Folder to load your contacts. The tool shows a preview of all contacts with their fields.
2
Select JSON as the output format. Choose which fields to include in the JSON output. Export and save the .json file.
VCF to JSON Field Mapping
This table shows the standard mapping from VCF properties to JSON keys. Use these key names for consistency with common API conventions.
| VCF Property | JSON Key (Flat) | Example Value |
|---|---|---|
| FN | fullName | “Jane Doe” |
| N (given) | firstName | “Jane” |
| N (family) | lastName | “Doe” |
| “jane@example.com” | ||
| TEL | phone | “+1-555-0123” |
| TEL (multiple) | phones (array) | [{“type”: “work”, “number”: “+1-555-0123”}] |
| ORG | organization | “Acme Corp” |
| TITLE | title | “Software Engineer” |
| ADR | address | {“street”: “123 Main St”, “city”: “Boston”, “state”: “MA”, “zip”: “02101”} |
| URL | url | “https://example.com” |
| NOTE | notes | “Met at conference 2024” |
| BDAY | birthday | “1990-05-15” |
| PHOTO | photo | Base64 string or URL |
For contacts with multiple emails or phone numbers, the flat JSON format uses arrays instead of single values: "emails": [{"type": "work", "address": "jane@company.com"}, {"type": "home", "address": "jane@gmail.com"}]. This preserves the TYPE labels from the VCF while also keeping the JSON structure clean. If you need to extract just the email addresses, you can filter the JSON output after conversion.
Method Comparison Table
| Criteria | Python | Node.js | Online Tool | Converter Tool |
|---|---|---|---|---|
| Custom JSON schema | Full control | Partial | No | Limited |
| jCard (RFC 7095) output | With library | No | Some tools | No |
| Multi-contact VCF | Yes | Yes | Depends | Yes |
| Handles vCard 4.0 | Yes | Partial | Varies | Yes |
| Technical skill needed | Medium | Medium | None | None |
| Data stays local | Yes | Yes | Depends | Yes |
| Best for | API integration | JS projects | Quick one-off | Bulk non-dev |
Handling Multi-Contact VCF Files
A VCF file can contain one contact or thousands. When converting to JSON, multi-contact files should output a JSON array where each element is a contact object. All four methods above handle this correctly: the Python script iterates over vobject.readComponents() which yields one card per BEGIN:VCARD block, and the Node.js library also returns an array of parsed contacts. If you need to split the VCF into individual files before converting, do that first.
If your downstream system expects individual JSON files (one per contact) instead of a single array, modify the Python script to write separate files:
for i, card in enumerate(vobject.readComponents(vcf_data)):
  with open(f"contact_{i}.json", "w") as f:
    json.dump(parse_contact(card), f, indent=2)
Common Problems and Fixes
JSON output contains escaped Unicode characters (\u00e9 instead of the actual character). The json.dump function in Python escapes non-ASCII characters by default. Add ensure_ascii=False to the json.dump call to output actual UTF-8 characters. The script in Method 1 already includes this flag.
Multiple emails or phones appear as a single value instead of an array. The basic Python script uses card.email.value which only returns the first email. To capture all emails, iterate: [e.value for e in card.contents.get("email", [])]. The same applies to TEL (phone) properties.
PHOTO data creates huge JSON files. VCF files with embedded contact photos (base64-encoded) produce very large JSON output. If you do not need photos, skip the PHOTO property during conversion. In the Python script, simply do not add a “photo” key to the contact object.
vCard 4.0 properties not parsed correctly. Some older parsing libraries (including vcard-json for Node.js) have incomplete vCard 4.0 support. If your VCF uses 4.0-specific features, use the Python vobject library instead, which has better 4.0 handling. Alternatively, you can convert the VCF to 3.0 first using our VCF version conversion guide.
Frequently Asked Questions
How do I convert VCF to JSON?
First, use a Python script with the vobject library to parse the VCF and output JSON, or use an online VCF to JSON converter like ConversionTab. Both approaches read the vCard properties and then output them as JSON key-value pairs.
What is the difference between flat JSON and jCard?
Flat JSON uses simple key-value pairs (e.g., “email”: “jane@example.com”), while jCard (RFC 7095) uses nested arrays that preserve every vCard property parameter and value type. Use flat JSON for APIs and databases. However, use jCard only if you need lossless round-trip conversion back to VCF.
Can I convert a VCF file with 1,000 contacts to JSON?
Yes. The Python and Node.js methods handle any number of contacts. The output is a JSON array with one object per contact. Online tools may have file size limits depending on the service.
Is there an npm package for VCF to JSON?
Yes. The vcard-json package (npm install vcard-json) parses VCF files and returns JSON objects. It supports vCard 2.1 and 3.0. However, for vCard 4.0, consider using the ical.js library instead, which has broader vCard support.
How do I convert JSON back to VCF?
If your JSON follows the jCard (RFC 7095) format, then standards-compliant parsers can convert it back to VCF losslessly. But if your JSON uses a flat custom schema, you will need to write a script that maps your JSON keys back to vCard properties and outputs the BEGIN:VCARD/END:VCARD structure.
Conclusion
Last verified: February 2026. Python script tested with vobject 0.9.7 on Python 3.12. Node.js method tested with vcard-json 0.5.2. VCF files tested from iCloud, Google Contacts, Outlook, and Samsung exports across vCard 2.1, 3.0, and 4.0.
To convert VCF to JSON, the Python script (Method 1) gives you the most control over the JSON schema and handles all vCard versions reliably. For JavaScript projects, the vcard-json npm package (Method 2) integrates directly into your Node.js workflow. For a quick one-off conversion without code, online tools (Method 3) or a VCF to JSON converter tool (Method 4) get the job done in clicks.
Three things to remember: use flat JSON for APIs and databases (simpler to query and integrate), add ensure_ascii=False in Python’s json.dump to preserve international characters, and handle multiple emails/phones as arrays instead of single values to avoid data loss.
