Introduction
There are two main ways that you can import data into CiviPlus:
Simple - using the import wizards pre-configured to handle Contacts, Activities, Contributions and Event Participants. These are best for simple, one-time, or occasional imports by non-technical users.
Advanced - using the API CSV Importer tool which can be configured to handle any data entity in CiviPlus. This is best is best for complex, large-scale, or automated imports and suitable for technical users.
A summary of the differences between the two methods is shown below
Feature | Built-in Import Wizards | API CSV Importer |
Access Method | User Interface (UI) driven | User Interface (UI) driven or API driven (command-line or scripts) |
Ease of Use | High (designed for non-technical users) | Low (requires technical knowledge) |
Field Mapping | Interactive field mapping interface | Interactive field mapping interface |
Data Transformation | Basic (limited transformation) | Advanced (flexible transformation) |
Batch Processing | Yes, with progress tracking | Yes, can be optimized for performance |
Custom Field Handling | Limited to basic mappings | Advanced handling of custom fields and multiple entities |
Error Handling | Immediate feedback in UI | Detailed error logging and handling |
Automation | No, manual process | Yes, suitable for automated imports |
Access Control | Managed through CiviCRM permissions | Managed through CiviCRM permissions |
Performance | Moderate, suitable for small to medium imports | High, optimized for large imports |
Integration | Limited to UI-based imports | Can be integrated with other systems |
User Role | Non-technical users | Developers and technical users |
Scalability | Limited scalability | Highly scalable |
Complex Data Imports
This article covers importing using the simple tools, there is a full guide covering more complex data imports here, along with supporting videos. here
Using the import wizards for different types of data
The import wizards for each data type are very similar, and so we have provided details for Contact Data which can be used as an exemplar for the other data types.
You can use the import wizards to create new records, or to update existing records. In the examples given below we are always creating new records.
For Contact data
For Contact data
Let's go through the steps to import contacts into CiviPlus, we will use a basic example but bear in mind that even this simple import wizard tool has a number of powerful features which can make it easy to populate your system with rich data about individuals and organisations.
First of all, you need to create a text file containing the contacts that you want to import. This needs to be in the Comma Separated Value format (CSV) - each contact record is a separate line in the file, and each contact field (email address, first name, last name etc) are separated by a comma. It often makes most sense to format your data first in Excel or Google Sheets before exporting to a CSV format, including a row showing the heading for each column. It really helps the import process if you make sure that the name of the column heading matches the name of the contact field in CiviPlus (see step 2 (a) below).
Examples of the spreadsheet and resulting CSV file are shown below:
In this example there are only a few fields for each contact record to be imported, but of course you can import as many fields as you like, including any custom fields you may have created in CiviPlus.
Now you are ready to start the import. Navigate to Contacts -> Import Contacts and you will see that there are 4 steps in the process:
Choose Data Source
The Date Source option shows "Comma Separated Value (CSV)". This is what we will be using so use the default.
For the Import Data File option click Choose File and find the CSV file that you created earlier, and if the first row contains column headers (as recommended) tick that box.
Now there are a few other options that control the way data is imported:
Contact Type - specify whether your contacts are Individuals or Organisations (the former in our example here).
For Duplicate Contacts - how do you want potential duplicates to be handled:
Skip: Reports and then skips duplicate import file rows - leaving the matching record in the database as-is (this is the default).
Update: Updates database fields with available import data. Fields in the database which are NOT included in the import row are left as-is
Fill: Fills in additional contact data only. Database fields which currently have values are left as-is.
No Duplicate Checking: Inserts all valid records without comparing them to existing contact records for possible duplicates.Duplicate Checking - CiviPlus has several built in rules for identifying potential duplicate records. See the separate article on deduplication for more details, but in this example we will leave this blank and the default rule will be used.
Import Field Separator - this defaults to a comma, which is what we can as we have a CSV file.
Date Format - it is important that the tool knows how to interpret any date fields that you are importing. Select the one from the list that matches the way your dates are formatted
Click on Continue to move to the next stage in the import wizard tool.
Match Fields
The importer tool read the CSV file and shows how it thinks each column in the file should map to a field in the CiviPlus contact record. It shows you values from the first two lines of the input file to help you confirm that the mappings are correct.
Note that because we used the CiviPlus contact record field names as the column headings in the CSV file the import tool has managed to get all the mappings correct. However, this may not always be possible and you may have to manually adjust the mapping by selecting the appropriate "Matching CiviCRM Field".
In this example, even though the tool has correctly matched the filed names, some of them have sub-types which we need to confirm. So for the email and address fields we need to say whether they are Home, Work, Billing, Personnel etc.
At the bottom of the page you have the option to save these mappings so that they can be re-used for subsequent imports.
Now we are ready to actually start the import - click Continue
Preview
This page shows you what the outcome will be if you continue with the import. In our example there are 10 rows in the import file, and all are valid. If there were issues with any of the rows to be imported they would be flagged, and you can download an import errors file that shows you exactly what is wrong with any of the data. You can then make corrections and start the import again.
At this point you can also decide to add the new contacts to new or existing groups, or add new/existing tags to them as part of the import process. For example, it might be useful to tag these new contacts as part of a particular import cohort. If you want to do this then complete the fields in one or more of these sections:
Add imported records to a new group
Add imported records to existing group(s)
Create a new tag and assign it to imported records
Tag imported records
Click 'Import Now' when you are ready to perform the import
Summary
Whilst the import is running a progress bar will show how many rows have been imported.
Once the import has completed, the Summary page is shown. Any errors will be flagged, and the error file can be downloaded so that the detailed can be reviewed and the issues corrected.
Now you should go and check that a sample of the imported contacts records to make sure that they look correct.
For Activities data
For Activities data
The process for importing Activities into CiviPlus is very similar to importing Contacts, so refer to the section above to understand the details.
Firstly you need to create the CSV Import File. Although you can import any of fields associated with an activity, including custom fields you may have created, these are the fields that you have to have as a minimum in in your CSV import file:
Activity Date
Activity Type
Target Contact ID (this is the internal ID that is assigned in CiviPlus when the contact is created).
Subject
Examples of a spreadsheet and CSV file for activities import are shown below:
Example spreadsheet
Example CSV file
Next, navigate to Contacts -> Import Activities and follow the same 4 step process described in detail in the section on importing contacts above.
For Contributions
For Contributions
The process for importing Contributions into CiviPlus is very similar to importing Contacts, so refer to the section above to understand the details.
Firstly you need to create the CSV Import File. Although you can import any of fields associated with a Contribution, including custom fields you may have created, these are the fields that you have to have as a minimum in in your CSV import file:
Email (used to match to an existing contact)
Financial Type
Total Amount
The fields that you need to include in your CSV will depend on how your system is configured in terms of contribution types, payment types etc. The example below assumes a very simple contributions set up - you may need to add many extra fields to your import file.
Examples of a spreadsheet and CSV file for activities import are shown below:Example spreadsheet
Next, navigate to Contributions -> Import Contributions and follow the same 4 step process described in detail in the section on importing contacts above.
For Event Participants
For Event Participants
The process for importing Event Participant into CiviPlus is very similar to importing Contacts, so refer to the section above to understand the details.
Firstly you need to create the CSV Import File. Although you can import any of fields associated with an Event Participant including custom fields you may have created, these are the fields that you have to have as a minimum in in your CSV import file:
Email (used to match against existing contact)
Event ID (This is the internal ID that is assigned when the Event is created in CiviPlus)
Participant Status
Examples of a spreadsheet and CSV file for activities import are shown below:
Example spreadsheet
Example CSV file
Next, navigate to Events -> Import Participants and follow the same 4 step process described in detail in the section on importing contacts above.
For Memberships
For Memberships
The process for importing Memberships into CiviPlus is very similar to importing Contacts, so refer to the section above to understand the details.
Firstly you need to create the CSV Import File. Although you can import any of fields associated with a Membership, including custom fields you may have created, these are the fields that you have to have as a minimum in in your CSV import file:
Contact Id or External Identifier or all the fields used in your Unsupervised Duplicate Matching rule (to match to an existing contact)
Membership Type
Membership Start Date
The fields that you need to include in your CSV will depend on how your system is configured in terms of contribution types, payment types etc. The example below assumes a very simple contributions set up - you may need to add many extra fields to your import file.
Examples of a spreadsheet and CSV file for activities import are shown below:
Example spreadsheet
Example CSV file
Next, navigate to Memberships -> Import Memberships and follow the same 4 step process described in detail in the section on importing contacts above.
Note: For data imports as part of a one-off migration from another CiviCRM system to CiviPlus Compuco has created a "plug and play" migrator tool. If you are interested in understanding more about this we would love to speak to you.