Understanding Google Contacts and vCard Custom Fields

If you are trying to back up or programmatically import contacts into Google Contacts using vCard (.vcf) files, you may have encountered issues with custom fields. Standard RFC vCard custom fields like X-CUSTOM-FIELD: value are often ignored on import, or worse, appended directly into the NOTE section as plain text.

The reason for this behavior is that Google Contacts relies heavily on Apple's vCard syntax extension specifications (vCard 3.0/4.0 item grouping) rather than generic custom key-value pairs.

The Solution: Google's vCard Grouping Syntax

To get Google Contacts to correctly parse and display custom fields, custom dates, or custom relationships, you must group properties using an itemN. identifier paired with an X-ABLabel extension tag.

1. Custom Dates (e.g., Anniversary)

To define custom dates such as an anniversary, use the X-ABDATE field grouped with X-ABLabel:

item1.X-ABDATE:1995-12-25
item1.X-ABLabel:Anniversary

2. Custom Relationships (e.g., Partner, Manager, Assistant)

For custom key-value text relationships, Google expects X-ABRELATEDNAMES:

item1.X-ABRELATEDNAMES:Jane Doe
item1.X-ABLabel:Partner

3. Custom Phone Numbers, Emails, or URLs

If you want to apply a custom label to standard contact attributes like phone numbers, emails, or websites, group the standard tag with an X-ABLabel tag:

item1.URL:https://github.com/example
item1.X-ABLabel:GitHub Profile
item2.TEL;type=pref:+1234567890
item2.X-ABLabel:Direct Line

4. Generic Custom Text Fields

For arbitrary text fields that do not map to built-in types, Google Contacts maps custom text reliably when exported or imported using the relationship tag approach:

item1.X-ABRELATEDNAMES:Project Apollo
item1.X-ABLabel:Codename

Python Code Example for Creating Compatible vCards

If you are writing a script in Python to generate Google Contacts-compatible .vcf files, you can construct entries as follows:

def generate_google_vcard(full_name, custom_label, custom_value):
    vcard_lines = [
        "BEGIN:VCARD",
        "VERSION:3.0",
        f"FN:{full_name}",
        f"N:{full_name};;;;",
        f"item1.X-ABRELATEDNAMES:{custom_value}",
        f"item1.X-ABLabel:{custom_label}",
        "END:VCARD"
    ]
    return "\n".join(vcard_lines)

# Example Usage
vcard_data = generate_google_vcard("John Smith", "Membership ID", "MEM-99283")
print(vcard_data)

Alternative Approach: Google CSV Format

If your application requires extensive custom data fields and vCard grouping rules prove too restrictive, consider exporting and importing using Google CSV format. Google's CSV import parser natively maps standard column headers without needing item grouping hacks.