The Importer accepts CSV, XLSX, and XLS files up to 100MB. The first row must contain column headers.
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. Just make sure each column has a clear header and each row represents one record.
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 will let you choose which worksheet to use in the lookup matching and preview steps.
Use headers that describe the data in the column. Clear headers improve smart mapping.
Good examples:
First Name
Last Name
Email
Phone 1
Address Line 1
Donor ID
Donation ID
Fund
Contribution Date
Amount
Avoid vague headers like Field1, Other, Misc, or Old Value.
If the old system has IDs, keep them in the file. Source IDs are especially important when later imports need to connect to records from earlier imports.
Common examples:
Source column | Why it matters |
|---|---|
| Helps match a person or organization from the source system |
| Helps identify an individual gift or transaction |
| Helps connect recurring giving history |
| Helps contact and donor imports find or create the correct household instead of relying only on the household name |
| 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.
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 will show values that need attention and can save those mappings for future imports. Creating new lookup values may require admin access.
Use Update existing records only when the file can identify the records to update.
Your file must include:
An Id column with CoolFocus record IDs, or
A DistinctImportId column that matches records imported from the same source, and
At least one mapped field to change.
The preview will show how many records matched and how many did not. You must type the number of matched rows before the update runs.
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 details on how CoolFocus matches or creates the household.
Prepare for a data migration
Import your data
Fix import issues and re-run rows
