Importer for Contacts Online Help

With Importer for Contacts for macOS you can convert CSV files, tab-separated text files, or Excel files to vCards. You can also import vCards with automatic address book group restoration.

Importing Files

Text Files

When importing a text file such as CSV files or tab-separated text, the app tries to determine the character encoding automatically. Because automatic detection can fail, a preview of the file will be displayed with all the special chars such as ü, ö, ß, ç, etc. highlighted in red. If necessary, adjust the character encoding until the preview of the text looks correct.
For more information about character encodings, visit this page.

Excel Files

When importing Excel files, you don’t have to deal with character encodings and line breaks at all. So if you have the choice, use Excel files for the import whenever possible. Older Excel files (with an .xls file extension) must be converted to a .xlsx Excel file first.

vCards

When importing vCards, Importer for Contacts can restore any address book group that the vCard was a member of at the time it was created. Groups that do not already exist will be created.

Mapping Fields

After reading the import file, the app tries to map the field names found in your import file to the corresponding fields and labels available in Contacts. By default, it also tries to detect custom labels. Auto-mapping does not work in each and every case, so double-check the auto-mapping and correct it if necessary. You can re-map the fields using different options at any time by choosing the “Map with Options…” command from the “Mapping” menu. If applicable, you can map a contact property or label to more than one source field in one go by selecting the rows in the mapping view while holding down the ⌘ key. Then choose an item from the “Contact Field” or “Label” popup menu and it will be assigned to all selected rows. Note: The several field types such as first name, last name, phone, street, postal code, etc., available in Apple Contacts (and therefore in Importer for Contacts as a mapping target) are a fixed set of fields defined by Apple and cannot be altered by the user (or an app developer). The only thing that users can edit are labels (for those fields that can have labels).

Saving Mappings

Importer for Contacts stores every field assignment you’ve made automatically. Unless turned off in the mapping options, the next time you open a file, the app compares the import file’s column headers with your custom mappings and will then map any match accordingly. For more flexibility, you can also save whole mappings for later use. For quick access, saved mappings appear in the “Mapping” menu. Choose “Manage Saved Mappings…” from the “Mapping” menu to rename or delete saved mappings.

Importing Contact Pictures

Importer for Contacts can import images placed in a cell of an Excel file. Note that images in Excel files created by exporting from Numbers cannot be extracted.

Determining the Contact Type

Use the “Contact Type” property to specify wether a contact should be marked as a company or not. By default, all imported contacts are marked as Person. In the app’s preferences, you can enter a list of terms such as “company, organization, firma, 1, true” or whatever your import file uses to mark a contact as a company.

Importing Label/Value lists

The app also provides a powerful feature to extract comma- or new-line separated labelled value lists from an import field. For example, if your import file contains a field with several phone numbers in the form “work: (123) 456-789, home: (987) 654-321”, map this to the “Phone” contact field and choose “Extract from field” from the “Label” popup menu. Importer for Contacts will then split the items into distinct phone numbers, assigning the given label to each of them. Label and value must always be separated with a colon. If no label is provided, the default label for the contact field type will be used.

Starting import or conversion

You can either import the contacts directly into Apple’s Contacts app or have them converted to vCard files to do the import manually or on another device.

Importing files into Contacts

You can specify which address book account you want to import the data to. It is recommended to close the Contacts app before you start the import. Sometimes data imported by third party applications does not show up in Apple Contacts right away. If in doubt, give Apple’s Contacts app a few minutes. If you want to assign your contacts to one or more groups, proceed as described in the next section.

Automatic Group Assignment

Unlike converting your data to vCards, when importing into Apple’s Contacts app, you can instruct Importer for Contacts to add the imported contacts to one or more groups. In your import file, simply specify a field with one or more group names, separated by a comma. Make sure that this field is then mapped to the target “Groups” field. If a group does not already exist in Contacts, it will be created. This way you can assign contacts to different groups very flexibly in one go.

Detecting Duplicates

The app can detect duplicates during the import. Unless a field from the source file is mapped to the “UID (read-only)” property, the display name of the converted record is used to detect duplicates. The display name is formed by macOS according to the settings in the Contacts app.
To avoid data loss, old duplicates are never touched but added to a group named “OLD DUPLICATES” and/or “NEW DUPLICATES”. Delete the duplicates by hand or use the “Merge Selected Cards” or “Look for Duplicates” commands in Contacts to get rid of them.

Detect old duplicates

This option assigns existing duplicate contacts in your address book for which there is a duplicate in your import file to the “OLD DUPLICATES” group.

Detect new duplicates

This option assigns the contact duplicates you just imported from your import file, for which there is a duplicate in your address book, to the “NEW DUPLICATES” group.

Mark the import process for future reference

You can add a text of your choice to the note of each imported contact. You can use these placeholders which will be substituted during the import:

• DATE: Will be substituted with the current date
• TIME: Will be substituted with the current time
• FILE: Will be substituted with the filename of the import file
• TRANSNUM: Will be substituted with a random transaction number for that import session. All contacts will get the same transaction number.

Converting files to vCards

Importer for Contacts can create a group vCard containing all converted contacts. You can also let the app create an individual vCard file for each converted contact. In both cases, the vCard 3.0 format will be used (as used by Contacts itself).