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.
cv_contact_id	Advanced. The contact's ID in CauseVox, as it appears in a report export. A row carrying this updates that exact contact and nothing else. See Matching on the CauseVox Contact ID.

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 works down this list and stops at the first match:

1. cv_contact_id matches a contact in your organization → that contact is updated.
2. reference_id matches an existing contact → that contact is updated.
3. email matches an existing contact's primary email → that contact is updated.
4. Nothing matches → a new contact is created.

Most files only ever use reference_id or email. cv_contact_id is the advanced option — see below.

Only the columns actually in your file are applied. A column you leave out, or a cell you leave blank, keeps whatever the existing contact already has.

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.

Matching on the CauseVox Contact ID

reference_id is the right column for most work — it holds your identifier, usually from the system you're migrating from. But some contacts have no reference ID and no email to match on: anyone created by a donation form, for instance. There is nothing on those rows for an import to recognise, so re-importing them creates duplicates.

For those, use cv_contact_id — the contact's ID in CauseVox:

1. Build a report on Contacts and include the ID column.
2. Export it, edit the fields you want to change, keep the ID column as-is.
3. Import the file with that column mapped to CauseVox Contact ID.

Each row updates exactly the contact that ID belongs to, regardless of name or email. This makes an export → edit → re-import round trip safe.

A few things to know:

• It takes precedence over reference_id and email. If a row has all three and they point at different contacts, the CauseVox Contact ID wins.

• It only accepts IDs from your own organization. An ID from anywhere else is treated as invalid.

• If the ID is invalid, it's cleared and the row is flagged before you process, so nothing is written using a bad value:

  "Invalid CauseVox Contact ID — "notarealcontactid" was cleared"

  Open the row, correct the ID, and the warning resolves. Leaving it means the row falls back to reference_id or email, and creates a new contact if neither matches.

• Leave the column blank for rows that should create new contacts. A blank cell is ignored.

TIP

cv_contact_id is for updating contacts that already exist in CauseVox. If you're migrating from another system, reference_id is still the column you want — put your old system's IDs there so future re-imports match.

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