Aller directement à la fin des métadonnées
Aller au début des métadonnées
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:

      • 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.

    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.

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.
  1. May 05, 2006

    Eric Howland dit :

    Tip:  If you want to export data from some application or even rearrange the data in a spreadsheet  in order to create a CSV file with headers that CiviCRM will automatically recognize then you need to figure out what headers civiCRM uses.

    To get this information put in one contact of the type you are interested in (individual, family or organization) by hand and then export it (use the find feature, then check the checkbox on the left side of your record and then choose Export Contacts from the drop down box above the alphabet)

    You will then get a choice to "Export PRIMARY contact fields" or to "Select fields for export". If you choose the first, you will get a CSV file with the headers in the first row and the data you entered in the second row.  If you chose the second you will get a list where you choose which type of record you want the data to come from and what fields within that data you want to have exported.

    Note that if your data set has several addresses or telephone numbers and you are wondering how to identify them. the output will misslead you. The output CSV will have a field specifying what kind of address the data is comming from. In contrast when you are inporting data that identification is not in either the dataset or the field names.  Instaid you will have a chance to specify what type of address each address field comes from (home, main, other or work) and what type of phone the number comes from (Phone, Mobile, Fax or Pager).   This specification is done on the same form that you would use to map unusual field names to CiviCRM names.  If you use this method the field names will auto-map but  you will still have to go through and specify what kind of address each address element is part of.  Fortunately if you are doing imports regularly you can save this specification.

  2. Aug 13, 2006

    Eric Howland dit :

    If you have defined fields that have multiple choice values and you are importing into those fields, the values that you want to import are the "Option Labels" not the "Option Values"

  3. Apr 19, 2007

    If you get to step 3:Preview, and CiviCRM reports that your import file contains only a fraction of the number of contacts that you know are there, 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. Excel is not so good at saving files as UTF-8. 

    What solved the problem for me was to open the csv file in OpenOffice Calc, and then re-save the file as a new csv file. 
    Then try your import again. 


Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.