|Prior Documentation Revision|
This section contains a prior version of CiviCRM Documentation. Go to Documentation Home for all current topics.
Preparing to Import Your Contact Data
CiviCRM provides an Import Wizard so you can easily migrate contact records from other sources into CiviCRM. For example, if your organization has contacts in Outlook, MS Access© or Excel©, and you want to start using CiviCRM to manage your relationships and interactions with these "constituents", you can easily import them using the Import Contacts option.
You can import many kinds of information about your constituents, including:
- Name, address, phone and email info (including multiple location addresses if needed)
- Custom data values that your organization has collected (e.g. voting precinct,, volunteer skills, interest areas, etc.)
- Information about related contacts (e.g. Spouse info, Employer info, etc.)
Before Importing Your Data...
In order to effectively migrate your constituent data to CiviCRM, you need to evaluate your data structure and content, and probably customize CiviCRM for your requirements. You should:
Data to be imported must be in the comma-separated-values format (CSV). Most applications will allow you to export records in this format. Consult the documentation for your application if you're not sure how to do this. Save this exported CSV file to your local hard drive (or an accessible drive on your network) - and you are now ready to run the import wizard.
- Review the contact fields available 'out of the box' (you can browse to the New Individual and New Organization input forms) and compare this to the columns (fields) which you currently use. Create Custom Data fields for any additional needed fields. When importing to custom data fields with multiple choice options, your import file should use the option LABELS. More info...
- Review the options used for address locations (e.g. Home, Work, School...), Individual Name Prefixes (Ms., Mrs., Mr...) and Suffixes (Jr., Sr.,...). Then customize / add options for these values as needed. More info...
- Review the types of relationship data you are (or want to) track (e.g. Parent, Spouse, Employer, Head of Household, etc.). Add relationship type definitions to CiviCRM as needed. More info...
Importing Organization and/or Household Records
In addition to Individual contacts, you can also import Organization or Household records. If your data contains records about people and (separately) records about Organizations, the best approach is to sort and export these two types of contact records separately. Then, import your Organization data first, followed by the Individual contacts.
This is particularly useful if your Individual contact data includes information about relationships to Organizations in your database (e.g. Jane Espinoza is a Board Member of The Oceans Institute, Tamara Stanley is an Employee of Global Media Corp.). When you import the 'people records', you can map the related Organization column(s) and CiviCRM will create the relationships for you automatically.
Import - Step by Step
Importing contacts is a four step process. Your user login must have *administer CiviCRM*permission. More info...
Step 1- Upload Data
- CiviCRM >> Import Contacts
- Click the Browse button, and navigate to the exported CSV file which contains your contact data.
- Often, the first row of an exported data file will contain the names of the fields in each column. Click First row contains columns headers if your file looks like this. If you're not sure, you can usually open the file in Excel©l or a text editor and look at the first row.
- Click on the radio button for the primary type of contact record in your data file. Select 'Individual' if each record in your file represents and individual person - even if the file also contains related Organization data (e.g. Employer Name, Employer Address, etc.). Select 'Organization' or 'Household' if each record in your file represents a contact of that type.
- Determine how you want the import to handle incoming records which appear to be duplicates of existing CiviCRM contacts.
- Click Continue
How are Duplicate Contacts Identified?
You can control which combination of contact fields is used to identify duplicate records by setting up CiviCRM Profile fields and enabling the Key to Match Contacts? field. For example, if you create a Profile with First, Middle, and Last Names plus Email Address - and check this property for all four - then duplicates are detected when all four values in your import row match an existing contact record. More info...
Which Duplicate Handling Option Should I Choose?
Generally, the safest option is Skip. This option ensures that no existing contact data is over-written - and you will have an opportunity to review the 'suspected' duplicates and re-import any which are actually unique new contacts.
However, if you are maintaining or updating contact data in the source application and then regularly synchronizing it to CiviCRM - you should consider either the Update or Fill options which give you the ability to update existing contact info in CiviCRM.
Step 2 - Match Fields
This step is where you match your import data columns to corresponding CiviCRM core and custom fields. If your import file contains column headers, these will be displayed vertically down the left side of this page. Data from the first 2 rows of your file are displayed to the right of the column headers (each row in this page represents a field in your incoming data file).
The import wizard will try to make intelligent guesses about what each column contains - and will select a value in the Matching CiviCRM Field drop-down if it has a good guess as to what's in that column.
- Work your way down this screen - row by row, verifying or updating the selected value in the Matching CiviCRM Field drop-down. Use your data file's column headers, and the actual data from the first rows of your file to verify the contents of each field.
- If there are 'fields' in your file that should not be imported, be sure to select -do not import-.
- If you have configured custom fields - they will be sorted towards the bottom of the drop-down select list.
- For address, email, and phone fields, you will also select a location type (e.g. Home, Work). For phone numbers, you will also select a phone type (e.g. Phone, Mobile, Fax...).
- If you have columns which have data about a related person or organization, scroll down in the drop-down list to the -related contact info- section and choose the appropriate value (e.g. Spouse of, Employee of...). A second drop-down is automatically provided for you to select the field for the related contact (e.g. for Employee of, you may select Organization Name, Address, etc.).
- If you think you may be importing additional data from the same data source, check Save this field mapping at the bottom of the page before continuing. Then enter a name for this 'mapping' (indicative of the source). The next time you import from the same source, you will be able to reload this mapping with a single click.
- Click Continue when you have finished mapping all the fields. You will have a chance to review your choices on the next screen before actually importing the data.
Load a Saved Field Mapping
If you have saved a field mapping during a prior Import, you will see a link to Load Saved Mapping. Clicking this link gives you a drop-down with the names of existing mapping(s). Select a mapping and click Load to reuse one of them.
If the structure of your import data has changed a bit since you last saved the import mapping. Make the appropriate changes. You can then either update the existing mapping, or save it as a new one.
Step 3 - Preview
This step allows you to review the mapping choices from step 2. It also provides feedback on rows in the input file which contain invalid data (e.g. mis-formatted email addresses, custom data values which do not match the expected data types, etc.). Finally, it warns you if there are apparent duplicate rows within the import file (e.g. two contacts with the same email address).
- Invalid and/or duplicate warnings will appear in red near the top of the screen. Click the provided link to download file(s) containing only the problem rows. The exact problem will be included in these error files.
- Depending on the number and type of errors, you may want to regenerate your import file. If so, simply click Cancel.
- If any of the choices in the Matching CiviCRM Field column (right side of your screen) are incorrect, click the Previous button and correct the drop-down selection(s).
- It is often useful to create a new CiviCRM Group from the imported contacts. Check Create new group... at the bottom of the screen and enter a name and optional description for the group. You can also have the new contacts added to one or more existing groups by clicking on the group name(s). Hold down the Ctrl key while clicking if you want to highlight more than one group.
- Verify that the number of records to be imported matches the number of rows in your CSV import file. If the number of rows reported by CiviCRM is less than expected the problem may be that your file is not encoded as UTF-8. Thus CiviCRM can not accurately detect where one line ends and the next begins. If you're having problems getting Excel to save the file as UTF-8, you can try using Open Office to open and save the file.
- Click Import Now to initiate import processing. (Up to this point, no changes have been made to your CiviCRM database.)
Step 4 - Import Summary
This screen displays the results of the import process, including the total number of records imported.
- If there were rows with duplicate contacts, this count is also displayed along with a download link (unless you requested 'No Duplicate Checking').
- If there were row(s) with errors, you will probably want to download the error file and review the problem data. Rows with invalid data are NOT IMPORTED. However, you may be able to simply correct the formatting or other errors and then repeat the import with just the corrected rows.
- If you created a new group from this import, a link is provided for you to review the new contacts as members of that group.