Online Help

Importing Files

Text Files

When a text file is imported, a CSV file or tab-delimited text for example, the app determines the character encoding on its own. That detection can fail, so the app shows a preview of the file with every special character such as ü, ö, ß and ç highlighted in red. Adjust the encoding until the file looks right in the preview.

For more about character encodings, see this page.

Excel Files

With Excel files you don't have to deal with character encodings and line breaks at all. If the data is available in both formats, take Excel. Older Excel files with the .xls extension have to be converted to an .xlsx file first.

vCards

When importing vCards, Importer for Contacts can restore every group the vCard belonged to at the time it was created. Groups that do not exist yet are created.

Mapping Fields

After reading the import file, the app maps the field names it finds in the column titles to the matching fields and labels in Apple's Contacts app, custom labels included. Automatic mapping does not succeed in every case, so check it and correct it where needed. Through the command "Map with Options…" in the "Mapping" menu you can have the automatic mapping done again at any time, with different options.

To make assigning fields and labels by hand easier, you can assign one field or label to several columns at once. Select the column rows in the mapping view with the ⌘ key held down, then choose an entry from the "Contact Field" or "Label" popup menu. It applies to every selected row.

The available field types themselves are fixed and unchangeable. First name, last name, phone, street, postal code and all the others come from Apple and can be extended neither by the user nor by a developer. Only the labels are free, and only on the fields that know labels.

Saving Mappings

Every field assignment is saved by Importer for Contacts automatically. The next time a file is opened, the app compares its column headers with your mappings and applies every match. This can be turned off in the mapping options. For more flexibility, whole mappings can also be saved under a name. For quick access they appear in the "Mapping" menu. "Manage Saved Mappings…" in the same menu renames and deletes them.

Importing Contact Pictures

An image placed in a cell of an Excel file is imported along with the contact. Images in Excel files that were exported from Numbers cannot be read. Backup Contact Pictures is a separate app that deals specifically with importing and exporting contact pictures in bulk.

Determining the Contact Type

The "Contact Type" property decides whether a contact counts as a company. Without that mapping, every imported contact is a person. Which terms your import file uses for it, "company, organization, 1, true" for example, is entered in the app's settings.

Importing Label/Value lists

A powerful feature extracts comma- or line-separated labeled values from a single field. If your import file holds a field with several phone numbers in the form "work: (123) 456-789, home: (987) 654-321", map it to the "Phone" contact field. Then choose "Extract from field" from the "Label" popup menu. Importer for Contacts splits the entries into separate phone numbers afterwards and applies the label stated for each of them. Label and value have to be separated by a colon. If the label is missing, the default label of the field type applies.

Starting import or conversion

The converted contacts can either be imported straight into Apple's Contacts app or turned into vCard files, to be imported by hand or on another device.

Importing files into Contacts

Before the import, set the account the data is to be imported into. Close Apple's Contacts app before the import starts. Data imported by a third-party app sometimes does not show up there right away. Give the app a few minutes if in doubt. If the contacts are to be assigned to groups as well, continue as described in the next section.

Automatic Group Assignment

When importing into Apple's Contacts app, the contacts can be assigned to one or more groups on request. Simply put a field with the group names in the import file, separated by commas, and map it to the "Groups" target field. Groups that do not exist yet in Apple's Contacts app are created. This distributes your contacts across any number of groups, very flexibly and in a single pass.

Detecting Duplicates

During the import the app detects duplicates. If no field from the source file is mapped to the "UID (read-only)" property, the display name of the converted record serves as the comparison. macOS composes the display name according to the settings in Apple's Contacts app.

To avoid data loss, duplicates are never touched. Depending on the setting they are added to a group named "OLD DUPLICATES" or "NEW DUPLICATES". Delete them by hand, or use the "Merge Selected Cards" and "Look for Duplicates" commands in Apple's Contacts app.

Detect old duplicates

This option assigns the contacts already present, for which there is a duplicate name in your import file, to the "OLD DUPLICATES" group.

Detect new duplicates

This option assigns the contacts just imported, for which there is a duplicate name among your contacts, to the "NEW DUPLICATES" group.

Mark the import process for future reference

A text of your choice can be written into the note of every imported contact. These placeholders are substituted:

• 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 creates either a group vCard holding all converted contacts or one vCard file per contact. In both cases the vCard 3.0 format is used, the one Apple's Contacts app uses itself.

Contact Fields Reference

Apple defines which fields a contact in Apple's Contacts app can have, and no third-party app can extend that list with field types of its own. Only labels can be adapted by the user with custom values. The field names in this reference are the ones Apple's Contacts app itself displays.

Fields that hold several values

Apple's Contacts app allows any number of entries per contact in the fields Phone, Email, Address, URL, Date, Related name, Instant message and Social profile. In fields of this kind every single entry has a label (home, work and so on, or a custom one). Several source columns of your import file can therefore be mapped to the same field.

Labels

A label marks the individual entries in fields that allow several values. Apple's Contacts app provides a fixed set of them per field type (home, work, other, mobile and more) and allows custom labels in most of these fields. As described above, a single source column in your import file may also contain a complete labeled list, for example "work: 123 456, home: 789 012"; the label is then set to Extract from field.

Address

Apple's Contacts app keeps an address in eight separate fields: Street, City, State, ZIP, Country, Country code, District and County. Each of these fields has to be mapped to a source column of its own. Note: there is no field for a preformatted complete address. Such an address cannot be imported, and it is not split up across the individual supported fields automatically either.

Instant message and Social profile

In the fields Instant message and Social profile the service is determined by the label. Importer for Contacts recognizes the common service names as a column header, among them Skype, Jabber, ICQ, LinkedIn, Facebook and Twitter.

Birthday and Date

Apple's Contacts app supports the birthday with a separate field intended just for it. All other dates belong in the field Date and are marked with a label there. An anniversary, for example, is an entry in the field Date with the anniversary label.

Single-value text fields

The fields Prefix, First name, Middle name, Last name, Suffix, Nickname, Maiden name, Company, Department, Job title and Note take exactly one entry each. Fields of this kind have no label. macOS forms the display name of a contact from these fields.

Phonetic fields

A phonetic spelling can be stored in Apple's Contacts app for four fields: Phonetic first name, Phonetic middle name, Phonetic last name and Phonetic company name. These fields stay empty as long as no source column is mapped to them.

Display name

macOS composes the display name itself from the name fields, in the order set in Apple's Contacts app. It is not available as a mapping target. If no source column is mapped to the UID field, duplicate detection compares the display name.

UID (read-only)

The UID is the identifier Apple's Contacts app assigns to a contact, and an import cannot overwrite it. When a source column is mapped to it, duplicate detection compares UIDs instead of display names.

Contact type

The field Contact type decides whether a contact is marked by Apple's Contacts app as a person or as a company. The default is person. Which terms in the source file stand for a company (company, organization, true or others) is set in the settings of Importer for Contacts.

Group name

Groups are lists that contacts in Apple's Contacts app can be assigned to. Importer for Contacts reads the group names from a source column, separated by commas, and creates the groups that are missing. This applies to imports into Apple's Contacts app; exporting your data to vCards naturally has no group assignment. The app writes the group names into the vCard file instead, for third-party apps that support this information.

Image

An image placed in a cell of an .xlsx file is imported along with the contact. Images in Excel files that were exported from Numbers cannot be read. For importing and exporting contact pictures in bulk there is the separate app Backup Contact Pictures.

Fields Apple's Contacts app does not support

Some columns from a Google Contacts or Outlook export have no counterpart in Apple's Contacts app, among them the PO box, the extended address line and the preformatted address. Columns of this kind can be mapped to the field Note or set to Ignore.

Column names recognized automatically

Importer for Contacts matches the column headers of the source file against a built-in list and assigns the appropriate field on its own. Exports from Google Contacts and Outlook are recognized with their original headers. The common alternatives to a field name are recognized as well, in upper and lower case, along with the names of the services. Examples:

• First name: First name, first, given name
• Last name: Last name, last, surname
• Company: Company, organization, organisation
• Phone: Phone, cell, fax, pager
• URL: URL, website, homepage, domain
• Maiden name: Maiden name, maiden
• Group name: group, groups, category, list
• Instant message / Social profile: Facebook, LinkedIn, Twitter, Skype, Jabber, ICQ

The built-in list is longer than these examples. Importer for Contacts shows the result of the mapping as soon as the file is opened. Columns without a match are mapped once by hand, and that mapping then applies to every later file with the same header.