The Importer accepts CSV, XLSX, and XLS files up to 100MB. The first row must contain column headers.
What this article is: how to format the spreadsheet so mapping and preview go smoothly. For what to migrate and in what order, see Prepare for a Data Migration. For running the wizard, see Import Your Data.
Start with a template when possible
On the upload step, choose Download template to get a starter CSV for the record type you are importing. The template shows common fields and helps you avoid missing required columns.
You can still use your own spreadsheet. Make sure each column has a clear header and each row represents one record.
Keep the file simple
Before uploading:
Remove title rows, notes, totals, subtotals, and blank sections
Put column headers in the first row
Use one record per row
Avoid merged cells
Convert formulas to values when possible
Remove hidden columns that should not be imported
Keep dates and numbers in consistent formats
Use plain values instead of color coding or comments
If the spreadsheet has multiple worksheets, the Importer lets you choose which worksheet to use in the lookup matching and preview steps.
Name columns clearly
Use headers that describe the data in the column. Clear headers improve smart mapping.
Good examples:
First NameLast NameEmailPhone 1Address Line 1Donor IDDonation IDFundContribution DateAmount
Avoid vague headers like Field1, Other, Misc, or Old Value.
Keep source IDs
If the old system has IDs, keep them in the file. Source IDs matter most when later imports need to connect to records from earlier imports.
Donor ID, Account ID, or Contact ID — helps match a person or organization from the source system
Donation ID or Transaction ID — identifies an individual gift or transaction
Recurring Donation ID — connects recurring giving history
Household Distinct Import Id — helps contact and donor imports find or create the correct household instead of relying only on the household name
Id or DistinctImportId — required for update imports when you are not using a CoolFocus record ID
Use the same Source System value when importing related files from the same system. Gift-to-donor linking details: Importing donors and contributions with source IDs.
Prepare lookup values
Lookup values are fields where the value must match an existing option or related record, such as a fund, role, program, service type, or status.
Before importing a large file:
Standardize spelling for lookup values
Remove duplicates caused by spacing or punctuation
Decide whether missing lookup values should be created or mapped to existing values
Keep a note of old values that should map to new names
The Match lookups step shows values that need attention and can save those mappings for future imports. Creating new lookup values may require admin access.
Update mode requirements
Use Update existing records only when the file can identify the records to update.
Your file must include:
An
Idcolumn with CoolFocus record IDs, orA
DistinctImportIdcolumn that matches records imported from the same source, andAt least one mapped field to change
The preview shows how many records matched and how many did not. You must type the number of matched rows before the update runs.
Household columns for contact and donor imports
Contact and donor import files can include a Household Name column, a Household Distinct Import Id column, or both, to place each imported person into a household automatically. See Importing Contacts and Donors for how CoolFocus matches or creates the household.