Adding Contacts in Batch

This guide walks you through creating a batch of contacts, either by entering them manually or importing from a spreadsheet.

Creating a New Batch

1. Go to Manage > Batches
2. Click Create
3. Give your batch a name (e.g., "Event Attendees" or "Board Members Import")
4. Select the Contacts tab

Adding Contacts Manually

Click Add to open the contact form. Fill in the required fields and any optional information.

Required Fields

Field	Description
Display Name	The contact's full name as it should appear
Created Date	When the contact record should be dated

General Information

Field	Description
Avatar Image	Profile picture URL
Reference ID	Unique identifier for updates and matching
Title	Name prefix (Mr., Mrs., Dr., etc.)
First Name	Contact's first name
Middle Name	Contact's middle name
Last Name	Contact's last name
Suffix	Name suffix (Jr., III, PhD, etc.)
Maiden Name	Previous surname
Deceased	Mark if contact is deceased
Can Contact	Allow general contact (email, phone, mail)
Tags	Add contact tags for organization
Custom Fields	Any custom fields configured for contacts

TIP

First Name and Last Name are optional but recommended. The Display Name is the primary identifier shown throughout the system.

Primary Email

Field	Description
Email	Primary email address
Can Email	Allow email communication

Primary Phone

Field	Description
Phone	Primary phone number
Can Call	Allow phone calls
Can Text	Allow text messages

Primary Address

Field	Description
Address Line 1	Street address
Address Line 2	Suite, apartment, etc.
City	City name
State	State or province
ZIP Code	Postal code
Country	Country name
Can Mail	Allow postal mail

Contact Preferences

The contact form includes several "can contact" checkboxes that control communication preferences:

• Can Contact - Global preference for any contact
• Can Email - Allow email communication
• Can Call - Allow phone calls
• Can Text - Allow SMS/text messages
• Can Mail - Allow postal mail

WARNING

These preferences are important for compliance with communication laws and donor preferences. Set them appropriately when importing contacts.

Editing and Removing Rows

• Edit: Click anywhere on a row to open the form and make changes
• Delete: Click the trash icon on the right side of a row

Importing from Spreadsheet

For large contact lists, importing from a spreadsheet is faster:

1. Click Import from Spreadsheet at the bottom of the batch
2. Select your CSV or Excel file
3. Map your columns to the correct fields (if needed)
4. Review the imported rows

See Importing from Spreadsheet for detailed instructions on the import process.

Supported CSV Columns

Below is the full list of columns supported when importing contacts from a CSV or Excel file.

Required

Column	Description
display_name	Contact's full name as it should appear
created_at	Date the contact record should be dated (e.g., 2024-01-15)

Name Fields

Column	Description
first_name	Contact's first name
middle_name	Contact's middle name
last_name	Contact's last name
title	Name prefix (Mr., Mrs., Dr., etc.)
suffix	Name suffix (Jr., III, PhD, etc.)
maiden_name	Previous surname

Contact Info

Column	Description
email	Primary email address
phone	Primary phone number

Address

Column	Description
line1	Street address line 1
line2	Street address line 2
city	City
state	State or province
zipcode	Postal/zip code
country	Country

Preferences

Column	Description
email_can_contact	Allow email communication (0 = no, 1 = yes)
phone_can_call	Allow phone calls (0 = no, 1 = yes)
phone_can_text	Allow text messages (0 = no, 1 = yes)
address_can_contact	Allow postal mail (0 = no, 1 = yes)
deceased	Mark as deceased (0 = no, 1 = yes)
can_contact	Allow general contact (0 = no, 1 = yes)

Other

Column	Description
reference_id	External or unique identifier — if a contact with the same reference ID exists, core fields and primary contact methods (email, phone, address) will be updated. Tags are added if not already present, and custom values are replaced.

Custom Fields (numbered, via column mapping)

Add custom field values using numbered columns:

Column	Description
contact_custom_field_1	Value for the first contact custom field
contact_custom_field_2	Value for the second contact custom field

Add more numbered columns (_3, _4, etc.) as needed.

Tags (numbered, via column mapping)

Apply tags using numbered columns:

Column	Description
contact_tag_1	Tag name to apply to the contact
contact_tag_2	Second tag for the contact

Add more numbered columns (_3, _4, etc.) as needed.

TIP

Custom fields and tags use numbered suffixes (_1, _2, etc.) and require the column mapping step during import. When you upload your file, map each numbered column to the correct field.

How Contacts Are Matched

When you upload the spreadsheet, each row is checked against your existing contacts. The import prefers reference_id matches first, falling back to primary email if a reference ID isn't provided.

• Row has reference_id matching an existing contact → the existing contact is updated.
• Row has an email matching an existing contact's primary email (no reference_id match) → the existing contact is updated.
• Neither matches → a new contact is created.

If two or more rows in the same batch share a primary email (and none of them match an existing contact), the review screen shows a warning like:

"Shares primary email with row 3 (no existing contact in this organization). This row will be merged into that contact; fields here may overwrite earlier values."

The rows are collapsed into a single new contact when you process the batch. Later rows' fields overwrite earlier ones, so if demographics differ between rows, use reference_id to keep them separate.

TIP

Matching happens at upload time. If you add a contact through the UI after uploading but before clicking Process Batch, the batch will not link to it — use the dedup suggestions afterward to merge. See Importing from Spreadsheet for the full matching flow.

Processing the Batch

When you're ready to finalize:

1. Review all contact information
2. Click Process Batch
3. Confirm the action

Important

Batch processing cannot be undone. Once processed, each contact becomes a permanent record. Double-check your data before processing.

After Processing

Once processed:

• Contacts appear in CRM > Contacts
• Communication preferences are set as specified
• Tags are applied to contacts
• Custom field values are saved

Tips and Best Practices

1. Include reference IDs - Essential for updating contacts via future imports
2. Set communication preferences - Respect donor privacy by setting preferences correctly
3. Use tags - Help organize contacts for future segmentation
4. Check for duplicates - Review for contacts that may already exist in your system
5. Validate email addresses - Ensure email formats are correct before importing
6. Test first - Import a small sample before the full file