Uploading donors via CSV

In short: Open Import Donors, download and fill in the Excel import template (keeping the sheet named donor-importer), choose your file under CSV File:, click Upload, review the preview and column mapping, then click Import. Your plan's donor limit must have room for the new donors.

Overview

If you already have a list of donors in a spreadsheet, you can import them all at once instead of adding each one by hand. You upload a file, map its columns to donor fields in a preview, and ActiveDonor creates the donors — including phone numbers, emails, addresses, tax details, a contact person and tags.

Before you start

You'll need:

• The Add Donor (or Manage Donors) permission.
• Room on your plan. The number of donors you can import is limited by your subscription. If a file would take you over your plan's donor limit, the uploader is blocked and you're shown an upgrade message.
• A file in a supported format: CSV, TXT, XLSX or XLS.

💡 Tip: Use the supplied template so the columns line up. On the uploader page, click "Use this Excel import template." to download activedonor-donor-import-template.xlsx.

⚠️ Important: The importer reads the sheet named donor-importer. Keep that sheet name from the template, or your rows won't be read and you'll see "Error on file upload. Ensure ActiveDonor template is used".

Uploading the file

Step 1: Open the donor uploader

Open the Import Donors screen.

Step 2: Download and fill in the template

Click "Use this Excel import template." to download activedonor-donor-import-template.xlsx, then fill in your donor rows. Keep the first sheet named donor-importer.

Step 3: Upload the file

Under Uploader:, choose your file in the CSV File: field and click Upload.

Step 4: Review the preview and column mapping

ActiveDonor shows a preview of your rows and lets you confirm which column maps to each donor field.

Step 5: Import

Click Import to bring the donors in, or go Back to start over.

Columns the template supports

The donor importer reads these columns from your sheet:

• type — the donor type (for example Individual, Company, Trust). If left blank, ActiveDonor sets it to Company when an entity_name is present, otherwise Individual.
• salutation, first_name, last_name, entity_name, gender, birthday, reference.
• require_certificate — set to Y, YES or 1 to mark the donor as needing a Section 18A certificate; anything else means no.
• language — defaults to English if left blank.
• cellphone, landline, fax — phone numbers; these are cleaned up automatically (for example a South African number entered as 27... is converted to start with 0).
• email.
• address_1, address_2, address_3, city, province, post_code, country — country defaults to South Africa if left blank.
• id_type, country_of_issue, id_reg_no, tax_no, trading_name — tax and identity details.
• contact_first_name, contact_last_name, contact_role, contact_email, contact_phone — a contact person on the donor.
• cat_1 to cat_12 — donor categories (tags). Each value becomes a donor tag, created if it doesn't already exist.

How values are handled

• Type is required. If missing, it's inferred — Company if there's an entity name, otherwise Individual.
• Entity name is required for entities; first name and last name are required for individuals.
• Phone numbers must have at least 10 digits, or the row fails with "Cellphone must have a minimum of 10 digits" (or the equivalent for landline).
• The first phone, email and address on each donor become the defaults.
• Post codes must be alphanumeric only (4–10 characters), or you'll see "Post code must contain only alphanumeric values."
• Each cat_1 to cat_12 value is turned into a donor tag.
• Empty rows are skipped automatically.

What this does not do

• It does not import receipts or donations — only donor records. Receipts have their own CSV upload (see Uploading receipts via CSV).
• It does not update existing donors — it creates new donor records from your rows.
• It does not override your plan's donor limit. If the file would exceed it, the upload is blocked.

Field reference

Column	Required?	Notes
type	No (inferred)	Defaults to Company if entity_name is present, otherwise Individual.
entity_name	Yes for entities	Required when the donor is an organisation.
first_name / last_name	Yes for individuals	Required when the donor is a person.
require_certificate	No	Y, YES or 1 = needs a Section 18A certificate; anything else = no.
language	No	Defaults to English.
cellphone / landline / fax	No	Minimum 10 digits for cellphone/landline; cleaned up automatically.
email	No	The donor's email address.
post_code	No	Alphanumeric only, 4–10 characters.
country	No	Defaults to South Africa.
id_type, country_of_issue, id_reg_no, tax_no, trading_name	No	Tax and identity details.
contact_first_name … contact_phone	No	A single contact person on the donor.
cat_1 … cat_12	No	Each value becomes a donor tag.

Common issues & solutions

What you see	What it means	How to fix it
"Error on file upload. Ensure ActiveDonor template is used"	The sheet wasn't read — usually the sheet isn't named donor-importer, or the file is empty.	Use the supplied template and keep the first sheet named donor-importer, then re-upload.
The Upload button is disabled / an upgrade message appears	The file would exceed your plan's donor limit.	Reduce the number of rows or upgrade your plan.
"Cellphone must have a minimum of 10 digits" (or Landline)	A phone number is too short.	Correct the number to at least 10 digits, or clear it, and re-upload.
"Post code must contain only alphanumeric values."	A post code contains spaces or symbols.	Use letters and digits only (4–10 characters).
My rows were skipped	Empty rows are skipped automatically; rows that fail validation are reported.	Fix the reported rows (missing required names, short phones, bad post codes) and re-upload.
Tags appeared that I didn't expect	Every value in cat_1 to cat_12 becomes a donor tag.	Check those columns for stray text before importing.

FAQ

Where do I get the donor import template? On the Import Donors page, click "Use this Excel import template." to download activedonor-donor-import-template.xlsx.

What file types can I upload? CSV, TXT, XLSX and XLS.

Why does it say the ActiveDonor template wasn't used? The importer reads the sheet named donor-importer. If that sheet is renamed or the file is empty, you'll see "Error on file upload. Ensure ActiveDonor template is used". Use the template and keep the sheet name.

Why were some of my rows skipped? Empty rows are skipped automatically, and rows that fail validation (missing required name fields, phone numbers under 10 digits, non-alphanumeric post codes) are reported so you can fix and re-upload.

Does the import update donors I already have? No — it creates new donor records. It doesn't match and update existing donors.

Related

• How do I import my existing donors from a spreadsheet?
• Adding a donor (types and required fields)
• Donor types explained
• Donor tags and categories
• Adding tax and ID information to a donor