Importer for Contacts Online Help
With Importer for Contacts for macOS you can convert CSV files, tab-separated text files, or from Excel files to vCards. You can also import vCards with automatic address book group restoration.
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.
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.
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.
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).
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.
Automatic Group Assignment
You can tell the app to add the imported contacts to one or more group(s). In your import file, simply provide a field with one or more group names, separated by comma. Make sure that this field is then mapped to the "Groups" property. If a group does not already exist in Contacts, it will be created.
Importing Contact Pictures
Importer for Contacts can import images placed in a cell of an Excel file. Note that the contact preview in the field mapping view does not display the assigned picture. This has technical reasons and is beyond the control of the app.
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.
Importing files into Contacts
You will be asked into which account you want to import the data. It's recommended to close Contacts before the import starts. In macOS 10.12, it’s not recommended to import contacts into a macOS Server CardDAV account. For some reason, all imported contacts and groups will perhaps be duplicated. Use the app’s vCard conversion feature instead. This seems to have been fixed by Apple in macOS 10.13.
The app can detect duplicates during the import. Unless a field from the source file is mapped to the "UID (read-only)" property, the full name of the converted record is used to detect old duplicates.
To avoid data loss, old duplicates are never touched but added to a group named "OLD DUPLICATES". Delete the duplicates by hand or use the “Merge Selected Cards” or “Look for Duplicates” commands in Contacts to get rid of them.
Appending a text line to the “Note” field
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).