SuiteCRM Data Import Guide: CSV Import, Field Mapping & Migration Best Practices

Every SuiteCRM deployment starts with the same critical step: getting your existing data into the system. Whether you’re migrating from another CRM, importing from spreadsheets, or loading data from an external database, the import process determines how useful your CRM is from day one. A botched import means duplicate records, broken relationships, missing data, and frustrated users who don’t trust the system.

This guide covers everything you need to know about importing data into SuiteCRM — from preparing your CSV files and mapping fields to handling duplicates, maintaining relationships, and troubleshooting common errors.

Understanding SuiteCRM’s Import Wizard

SuiteCRM includes a built-in Import Wizard accessible from any module. Navigate to the module you want to import into (e.g., Contacts, Leads, Accounts) and select Import from the module actions menu. The wizard walks you through four steps: upload your file, map fields, check for duplicates, and run the import.

The Import Wizard supports CSV files as the standard import format. It auto-detects file properties like delimiter type (comma, tab, semicolon), enclosure characters (quotes), and date formats — making basic imports straightforward. It also saves mapping configurations from previous imports, so repeated imports of similar data are faster.

Step 1: Prepare Your Data Before Importing

The most important work happens before you touch SuiteCRM. Dirty data imported into a clean CRM creates a dirty CRM.

Clean Your Source Data

Open your spreadsheet in Excel, Google Sheets, or LibreOffice Calc and perform these essential cleaning steps.

Remove duplicates. Use your spreadsheet’s built-in duplicate detection to find and merge duplicate contacts, companies, and leads before importing. It’s far easier to deduplicate in a spreadsheet than in CRM after import.

Standardize formatting. Ensure phone numbers follow a consistent format (e.g., +1-555-123-4567), addresses use standard abbreviations (St, Ave, Blvd), country names match a single format (USA vs United States vs US — pick one), and date fields use a consistent format (YYYY-MM-DD is safest for SuiteCRM).

Fill required fields. SuiteCRM requires certain fields for each module — typically Last Name for Contacts/Leads and Name for Accounts. Ensure every row has values for required fields, or the import will skip those records.

Validate email addresses. Remove obviously invalid emails (missing @ sign, typos in domains). Invalid emails cause bounce issues later when you use SuiteCRM for email campaigns.

Map your columns to SuiteCRM fields. Before importing, identify which columns in your spreadsheet correspond to which SuiteCRM fields. Rename column headers to match SuiteCRM field labels — this makes the mapping step faster and reduces errors.

Save as CSV (UTF-8)

SuiteCRM requires CSV files encoded in UTF-8. When saving from Excel, choose “CSV UTF-8 (Comma delimited)” as the file type. When saving from Google Sheets, use File → Download → Comma Separated Values (.csv). Non-UTF-8 encoding causes special characters (accents, symbols) to display incorrectly.

Step 2: Import in the Right Order

This is the most commonly missed step — and it causes the most problems. SuiteCRM maintains relationships between modules (Contacts belong to Accounts, Opportunities belong to Accounts, etc.). To preserve these relationships during import, you must import parent records before child records.

The correct import order:

1. Accounts (companies/organizations) — import first because Contacts, Opportunities, Cases, and most other records relate to Accounts.
2. Contacts — import second with an Account Name column that matches the Account names you just imported. SuiteCRM automatically links Contacts to their Accounts.
3. Leads — import separately (Leads don’t relate to Accounts until converted).
4. Opportunities — import with Account Name to link deals to companies.
5. Activities (Calls, Meetings, Notes, Tasks) — import last, linking to Contacts or Accounts via name or ID.
6. Cases — import with Account Name and/or Contact Name for relationship linking.

Skipping this order results in orphaned records — Contacts with no Account, Opportunities floating without company context. Fixing this after import requires manual cleanup that takes hours.

Step 3: Map Fields in the Import Wizard

After uploading your CSV, the Import Wizard presents a field mapping screen. Each column in your CSV appears on the left, with a dropdown menu on the right to select the corresponding SuiteCRM field.

Tips for accurate mapping:

Use SuiteCRM’s sample CSV template (downloadable from the Import page) as a reference for available fields and expected formats. Map essential fields first — Name, Email, Phone, Account Name, Address. For fields you don’t want to import, select “Skip” from the dropdown. Use the “Default Values” section to set values that apply to all imported records — for example, set Assigned User to a specific rep or set Lead Source to “Imported Data.”

The Import Wizard remembers your mapping configuration. For recurring imports (e.g., monthly lead lists from a partner), save the mapping template and reuse it.

Handling Dropdown Fields

SuiteCRM dropdown fields store internal IDs, not display labels. When importing, you can use either the display label (e.g., “Closed Won”) or the database ID (e.g., “Closed_Won”). The Import Wizard accepts both, but using display labels is easier and less error-prone.

If your source data uses different values for dropdown fields (e.g., your spreadsheet says “Won” but SuiteCRM’s dropdown says “Closed Won”), either update the spreadsheet values to match SuiteCRM’s dropdown options, or add the missing values to SuiteCRM’s dropdown list before importing (Admin → Studio → Module → Fields → edit the dropdown).

Step 4: Handle Duplicates

The Import Wizard includes duplicate detection. During import setup, you can choose to create new records only (no duplicate checking — fastest but riskiest), create new records and update existing ones (checks for matches based on fields you specify), and the matching fields to use for duplicate detection (email, name + company, phone number, or external ID).

Best practice: For initial imports, use “create only” since there’s nothing to duplicate against. For subsequent imports (e.g., updating records from an external system), use “create and update” with email address or external ID as the matching field.

For large-scale imports where the built-in duplicate detection isn’t sufficient, consider using the SuiteCRM Store’s Smart Importer plugin, which offers enhanced duplicate detection across modules, the ability to update, skip, or merge duplicates, automatic backup before import, and support for CSV, XLS, and XLSX formats.

Step 5: Run and Verify

Click “Run Import” and wait for the wizard to process your file. After completion, SuiteCRM displays a summary showing records created successfully, records updated (if using create/update mode), duplicate records found and skipped, and records with errors (with error details).

Verify your import immediately:

Check record counts — does the number of imported records match what you expected? Open several records and verify all fields populated correctly. Check relationships — do Contacts show their linked Account? Do Opportunities show Account and Contact relationships? Verify dropdown values — did Lead Source, Status, and other dropdowns import with correct values? Check for encoding issues — do names with special characters (accents, umlauts) display correctly?

If something went wrong, SuiteCRM provides an “Undo Import” option that reverses the entire import. Use this before anyone starts working with the imported data.

Importing from Other CRMs

From Salesforce

Export from Salesforce using Data Export (Setup → Data → Export). Salesforce exports to CSV with relationship IDs. Map Salesforce Account IDs to SuiteCRM Account Names for relationship preservation. See our dedicated Salesforce to SuiteCRM migration guide.

From HubSpot

HubSpot’s export includes Contacts, Companies, Deals, and Activities. Export each object separately. Map HubSpot’s “Associated Company” field to SuiteCRM’s Account Name for relationship linking. Read our SuiteCRM vs HubSpot comparison.

From Zoho CRM

Zoho’s bulk export creates CSV files per module. The import process mirrors the standard CSV import. Map Zoho’s Account Name and Contact Name fields to SuiteCRM equivalents. See our SuiteCRM vs Zoho comparison.

From Spreadsheets

If your business has been managing contacts in Excel or Google Sheets, the good news is that CSV import is the native format. Clean the data, organize columns, save as UTF-8 CSV, and import using the wizard.

API-Based Import for Large Datasets

For imports exceeding 10,000 records or requiring complex relationship mapping, SuiteCRM’s REST API provides a programmatic alternative to the Import Wizard. API imports can handle complex parent-child relationships in a single automated process, transform data on the fly (reformatting phone numbers, splitting full names into first/last), validate against custom business rules before creating records, run in batches during off-peak hours to avoid performance impact, and log every operation for audit trails.

Custom import scripts using the REST API are a common SuiteCRM development task. TechEsperto builds migration scripts for complex data transitions.

Troubleshooting Common Import Errors

“Internal server error” during import. Your import file is too large for PHP’s memory limit. Increase memory_limit in php.ini (512M or 1024M) and max_execution_time (300 seconds). Alternatively, split large files into smaller batches. See our performance optimization guide for PHP tuning.

Records created but relationships missing. You likely imported Contacts before Accounts, or the Account Name in your Contacts CSV doesn’t exactly match the Account Name in SuiteCRM. The match must be exact — including capitalization and spacing.

Special characters displaying as garbled text. Your CSV isn’t UTF-8 encoded. Re-save as UTF-8 from your spreadsheet application and re-import.

Dropdown values not importing. Your CSV values don’t match SuiteCRM’s dropdown options. Either update the CSV to match exactly, or add the missing dropdown values in SuiteCRM before importing.

Duplicate records created. You didn’t enable duplicate checking, or the matching field (email, name) has variations between your CSV and existing SuiteCRM records. Run a deduplication process after import — Admin → Studio → Module → merge duplicates, or use a deduplication plugin.

Import seems to complete but no records appear. Check that you selected the correct module for import. Verify that the CSV has data rows (not just headers). Check the SuiteCRM log (suitecrm.log) for error details.

When to Get Professional Help

Data migration is the highest-risk phase of any CRM deployment. Common scenarios where professional SuiteCRM consulting prevents costly mistakes include migrating 50,000+ records with complex relationships across multiple modules, migrating from CRMs with different data structures (Salesforce custom objects, Dynamics entities), importing historical activities (emails, calls, meetings) linked to the correct contacts, handling custom field types (multi-select dropdowns, related fields, calculated fields), and migrating data that must maintain audit trails for compliance.