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 Data > Batch Import
2. Click Create and confirm — the batch is named with the date and time; rename it on the batch page if you like (e.g., "Board Members Import")
3. Under What do you want to import?, choose Contacts

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; if more than one does, the row is refused. 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.
crm_organization_id	Links the contact to a CRM organization, by its CauseVox ID or its reference ID. An ID from another organization is cleared with a warning. A reference that still isn't found when the batch is processed fails the row — the contact isn't imported. Import the organization first, or put it in the same batch and click Resume batch once the batch finishes. A reference more than one organization has fails the row too, until you use that organization's CauseVox ID.
crm_organization_role	The contact's role at the organization in crm_organization_id (e.g., Board Member). It's matched to your organization roles regardless of capitalization. A role that isn't on that list imports as written, with a warning. It's set only when the contact is newly linked to the organization; a contact already linked keeps the role it has.
crm_household_id	Adds the contact to a household, by its CauseVox ID or its reference ID. The household must be imported first, or be in the same batch. A row naming a household that isn't in your organization fails — the contact isn't imported. If the household is in the same batch, click Resume batch once the batch finishes to import those rows. A contact already in the household isn't added twice, and the contact's other households are kept.

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.

Relationships (numbered, via column mapping)

Link the row's contact to other contacts — a spouse, a parent, a colleague. Each numbered group is one relationship:

Column	Description
contact_relationship_contact_id_1	The other contact, by its CauseVox ID or its reference ID. It can be a contact in the same batch.
contact_relationship_type_1	What the other contact is to this row's contact. Parent means the other contact is this contact's parent.
contact_relationship_reciprocal_type_1	What this row's contact is to the other contact (Child, for the row above). Leave it blank when the type is in your relationship list — it's filled in from the list.
contact_relationship_start_date_1	When the relationship started (YYYY-MM-DD). Optional.
contact_relationship_end_date_1	When it ended (YYYY-MM-DD). Optional.

Use _2, _3 and so on, up to _10, for a contact's other relationships.

• Write each relationship once, on either person's row. It's saved on both contacts. Writing it on both rows is fine — it's saved once.
• A relationship needs a way to find this row's contact, so give the row a reference_id (or a cv_contact_id). A row with neither that isn't matched to an existing contact by email keeps its contact, but its relationships are dropped at upload with a warning.
• Each relationship becomes its own row on the batch's Relationships tab, where you can review, edit or delete it before processing. See Relationships in a Batch.
• Relationships are processed after contacts, so the other contact can be anywhere in the same file.

Add your relationship types and roles first

Relationship types come from CRM Settings > Contact > General > Contact Relationships, and organization roles from CRM Settings > Organizations > General > Organization Roles. Add any that your file uses before importing, so dropdowns (edit dialogs, segment filters) offer them. A type or role that isn't on the list still imports as written, with a warning — but a type that isn't on the list needs its reciprocal type in the file.

TIP

Custom fields, tags and relationships 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 and group number.

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. If more than one contact already has that reference ID, the row is refused.
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.

When a row matches by cv_contact_id or email and that contact has no reference ID yet (blank, or only an automatic ref-… one), it takes the row's reference_id, so later files can match it by reference. A contact that already has a reference ID keeps it, and a reference ID another contact already has is never copied.

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, even when their reference_ids differ. Later rows' fields overwrite earlier ones, and only the first row's reference_id is kept. If two people share an email (a couple, a family), give the email to one of them only.

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
• Relationships appear on both contacts' pages. A relationship whose other contact couldn't be found is marked with an error on the Relationships tab; the contact itself is still imported

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