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.
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.
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.
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 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.
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.
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 shows 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 how CoolFocus matches or creates the household.
• Migrating Data Into CoolFocus
• Prepare for a Data Migration
• Import Your Data
• Fix Import Issues and Re-Run Rows
• Importing donors and contributions with source IDs
• Importing Contacts and Donors
