Convert structured contact data from JSON format into standard VCF (vCard) files, which can be imported into address books (Google Contacts, Outlook, iPhone, Thunderbird, etc.).

You might have JSON data from multiple sources that you need to turn into actionable contacts. Common scenarios include:

A manual copy-paste of 1,000 JSON entries into a phone book would take days. A converter does it in seconds.

Before you upload your JSON file to a random website, consider this:

| Feature | Benefit | |---------|---------| | Auto‑detect JSON structure | No manual mapping for standard exports (e.g., from Google Contacts JSON). | | Preserve custom fields | Map unknown JSON keys to X- extension properties. | | Photo handling | If JSON contains base64‑encoded image or URL, embed photo in vCard (PHOTO). | | Groups/Categories | Convert JSON group labels to vCard CATEGORIES. | | Internationalization | Support Unicode names, addresses, and notes (UTF‑8). | | CLI version | For developers: json2vcf input.json -o output.vcf. | | REST API | POST JSON → receive VCF file (for integration with other apps). | | Privacy filter | Strip or mask certain fields (e.g., remove secondary phone numbers). |

JSON is a lightweight data-interchange format. It uses key-value pairs and ordered lists. A typical JSON contact object looks like this:

[
"name": "John Doe",
    "phone": "+1-555-123-4567",
    "email": "john.doe@example.com",
    "company": "Acme Inc."
]

Strengths: APIs, databases, web storage. Weakness: Cannot be imported directly into a phone's address book.

[
"CHROM": "chr1",
    "POS": 12345,
    "ID": "rs1234",
    "REF": "A",
    "ALT": ["T"],
    "QUAL": 100,
    "FILTER": "PASS",
    "INFO": 
      "AF": 0.5
    ,
    "FORMAT": "GT",
    "SAMPLE": 
      "GT": [0, 1]
]

##fileformat=VCFv4.2
##FORMAT=<ID=GT,Number=1,Type=String,Description="Genotype">
#CHROM  POS     ID      REF     ALT     QUAL    FILTER  INFO    FORMAT  SAMPLE
chr1    12345   rs1234  A       T       100     PASS    AF=0.5  GT      0|1

For large JSON arrays (10,000+ contacts):

Even with a good converter, things go wrong. Here is the troubleshooting guide.

| Problem | Likely Cause | Solution | | :--- | :--- | :--- | | Output VCF is empty | JSON is an object {} not array [] | Wrap your object in square brackets: [...] | | Phone numbers missing | JSON key is "mobile", not "phone" | Edit the JSON to use "phone" OR use a converter that allows custom key mapping. | | Names appear as "Undefined" | JSON key is "fullName", not "name" | Pre-process JSON to rename keys. Use "Find and Replace" in Notepad++. | | Special characters (é, ñ) are garbage | Encoding mismatch | Ensure converter outputs UTF-8. If not, use a script. | | Only first contact imports | Missing END:VCARD or separators | Open VCF in text editor. Ensure each contact block ends with END:VCARD. |