Updating Existing Records

Use the reference_id field to update records that already exist in CauseVox. This works for donations, pledges, installments, and contacts. It's useful for correcting data or syncing with external systems.

How It Works

When you process a batch:

1. The system checks if a record with that reference_id already exists
2. If found: The existing record is updated with the new data
3. If not found: A new record is created
4. If more than one record already has that reference_id: The row is refused, because it can't tell which one to update. Neither record changes

This makes batch imports idempotent - you can safely re-import the same data without creating duplicates.

Only the columns in your file are applied

A column you leave out of the spreadsheet — or a cell you leave blank — is treated as "no opinion" and the existing value is kept. That includes the yes/no preference columns like deceased and can_contact. To change one of those, include the column and give it a value.

Contacts have a second matching option

Contacts can also be matched on cv_contact_id, their ID in CauseVox, which takes precedence over reference_id and email. It's the way to update contacts that never had a reference ID — see Matching on the CauseVox Contact ID.

Setting Up Reference IDs

For New Records

When creating records, include a unique reference_id:

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-001,John Smith,100.00,USD,2024-01-15,abc123-def456
DON-002,Jane Doe,250.00,USD,2024-01-16,abc123-def456

Best Practices for Reference IDs

• Use your external system's ID (e.g., from your old CRM)
• Create a consistent naming convention (e.g., DON-2024-001)
• Keep them unique across all donations or pledges
• Store them in your spreadsheet for future reference

TIP

If you don't provide a reference_id, the system generates one automatically. You won't be able to update that record via batch import later using a reference ID. For contacts there is still a way back in — export them with the ID column and re-import using cv_contact_id.

---

What Gets Updated

When updating an existing record, not all fields are updated. This protects important relationships and prevents data corruption.

Donations & Pledges

Fields That WILL Update

These fields are updated when you re-import a donation or pledge with a matching reference_id:

Category	Fields
Basic Info	display_name, amount, currency_code, created_at
Donor Details	first_name, last_name, email, company_name
Address	line1, line2, city, state, zipcode, country
Associations	campaign_id, donation_form_id, site_id, project_id, team_id, network_id
Settings	anonymous, anonymous_type, comment
Tribute Info	tribute_type, tribute_honoree_name
Revenue Payment	revenue_status, revenue_payment_method, revenue_payment_channel, revenue_payment_reference, revenue_payment_meta
Tags	Added if not already present (safe to re-import)
Custom Fields	Replaced with new values on each import
Contact Link	contact_id (only if explicitly provided)

Fields That Will NOT Update

These fields are skipped for existing records to prevent duplicates:

Field	Why It's Skipped
Revenue splits	Only created on initial import. Re-importing does not add, remove, or modify splits.
Revenue credits	Only created on initial import. Re-importing does not add, remove, or modify credits. To add or correct credits on donations already imported, use a Credits batch.
Revenue solicitors	Only created on initial import (applies to both revenue and expected revenue solicitors). Re-importing does not add, remove, or modify solicitors.
Tribute soft credits	Only created on initial import to prevent duplicates.
Auto-contact creation	Existing records already have contact handling.

Important

If a donation already has a contact linked and you re-import without specifying contact_id, the existing contact link is preserved. We don't automatically create a new contact for existing records.

Installments

Fields That WILL Update

Category	Fields
Basic Info	amount, created_at
Revenue Payment	revenue_status, revenue_payment_method, revenue_payment_channel, revenue_payment_reference, revenue_payment_meta
Tags	Added if not already present (safe to re-import)
Custom Fields	Replaced with new values on each import

Fields That Will NOT Update

Field	Why It's Skipped
Revenue splits	Only created on initial import. Re-importing does not add, remove, or modify splits.
Revenue credits	Only created on initial import. Re-importing does not add, remove, or modify credits.
Revenue solicitors	Only created on initial import. Re-importing does not add, remove, or modify solicitors.

Contacts

Contacts are matched on cv_contact_id first, then reference_id, then primary email — see How Contacts Are Matched.

Fields That WILL Update

Each of these updates only when the column is in your file with a value. Omit the column, or leave the cell blank, and the contact keeps what it already has.

Category	Fields
Basic Info	display_name, title, first_name, middle_name, last_name, suffix, maiden_name, deceased, can_contact
Primary Email	email, email_can_contact (upserts existing primary email)
Primary Phone	phone, phone_can_call, phone_can_text (upserts existing primary phone)
Primary Address	line1, line2, city, state, zipcode, country, address_can_contact (upserts existing primary address)
Tags	Added if not already present (safe to re-import)
Custom Fields	Replaced with new values on each import
Reference ID	reference_id — set only on a contact matched by cv_contact_id or email that has no reference ID of its own yet (blank, or only an automatic ref-… one); a contact's existing reference ID is never replaced, and one another contact already has is never copied
Organization / Household	crm_organization_id, crm_household_id — a link is added when the contact isn't already linked; existing memberships are never removed or moved (safe to re-import). crm_organization_role is set only on a new link
Relationships	contact_relationship_* — a relationship is added when the two contacts don't already have one of that type; existing relationships are never removed or changed (safe to re-import). The same two contacts with a different type get a second relationship, unless its reciprocal side already belongs to another relationship between them — that row is refused

WARNING

The preference columns — deceased, can_contact, email_can_contact, phone_can_call, phone_can_text, address_can_contact — follow the same rule. A file that never mentions can_contact leaves it exactly as it was; it does not reset anyone to contactable.

TIP

Non-primary contact methods (secondary emails, phones, addresses) are not affected by re-imports.

created_at is only used for new contacts. An existing contact keeps its original created date.

---

Example: Updating Records

Scenario 1: Correct an Amount

Original import:

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-001,John Smith,100.00,USD,2024-01-15,abc123-def456

Correction import:

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-001,John Smith,150.00,USD,2024-01-15,abc123-def456

Result: The existing donation's amount changes from $100 to $150.

Scenario 2: Add Missing Information

Original import (minimal data):

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-002,Jane Doe,250.00,USD,2024-01-16,abc123-def456

Update with more details:

reference_id,display_name,amount,currency_code,created_at,campaign_id,email,city,state
DON-002,Jane Doe,250.00,USD,2024-01-16,abc123-def456,jane@example.com,Boston,MA

Result: Email and address are added to the existing donation.

Scenario 3: What Doesn't Change

If you import a record that exists but include different tribute information:

reference_id,display_name,amount,tribute_type,tribute_honoree_name,...
DON-001,John Smith,150.00,in_memory_of,Robert Smith,...

Result:

• The tribute_type and tribute_honoree_name fields ARE updated
• BUT a new tribute soft credit is NOT created (that only happens for new records)

---

Re-Importing Data Safely

Step 1: Export Your Existing Data

Before re-importing, export your current data as a backup.

Step 2: Include Reference IDs

Make sure your import file has the same reference_ids as existing records.

Step 3: Review Changes

After importing, check a few records to verify updates applied correctly.

---

When to Use Updates vs. New Records

Use Case	Approach
Correcting typos or amounts	Update (same reference_id)
Adding missing information	Update (same reference_id)
Recording a new donation	New (new or no reference_id)
Migrating from another system	New with reference_ids from old system
Syncing with external system	Update (use external system's IDs)

---

Troubleshooting

"I updated but nothing changed"

• Verify the reference_id matches exactly (case-sensitive)
• Check that the record type matches (donation vs. pledge)
• Confirm the record was processed (not just added to batch)

"A new record was created instead of updating"

• The reference_id didn't match an existing record
• Check for typos or extra spaces in the reference_id
• The original record might not have had a reference_id set

"Contact wasn't updated"

• For existing records, contact is only updated if you explicitly provide contact_id
• Auto-contact creation only happens for new records