Importing from Spreadsheet

Upload a CSV or Excel file to add multiple donations, credits on donations, pledges, contacts, households, organizations, notes, or tickets at once. This is the fastest way to import large amounts of data.

Before You Start

1. Get the sample spreadsheet - Download our template to ensure correct formatting
2. Prepare your data - Match your columns to our field names
3. Check your limits - Maximum 25,000 rows per file

Step-by-Step Import

Step 1: Open the Import Dialog

1. Create or open a batch
2. Click Import from Spreadsheet at the bottom

Step 2: Upload Your File

• Drag and drop your file, or click to browse
• Supported formats: CSV (.csv) and Excel (.xlsx)

Step 3: Map Your Columns

Every import shows a mapping screen. Nothing is mapped automatically — map each column yourself, or load a saved mapping template:

1. For each field, select the matching column from your file
2. Leave unmapped fields blank if not used
3. Click Continue

Step 4: Review and Confirm

• Check the preview of imported data
• Look for any errors or warnings
• Click Import to add the rows to your batch

WARNING

The import adds rows to your batch but doesn't process them yet. Review the data before clicking Process Batch.

---

How Records Are Matched & Collapsed

Batch imports look up and collapse records in two stages: once at upload (when you click Import from Spreadsheet) and once during Process Batch. Understanding this helps you read the warnings that appear in the review screen.

Stage 1 — Upload (system-level matching)

At upload, each row is checked against existing CauseVox data:

• Donations, pledges, installments, tickets with a blank contact_id but a filled email: the import looks for an existing contact in your organization whose email (primary or secondary) matches. If found, the row is linked to that contact automatically. A donation, pledge or installment row with a crm_organization_id is an organization gift and is never linked to a contact by email.
• Donations, pledges, tickets, attendees with no contact_id, no email and no organization are matched on the person's name, ignoring capitalization: first the first and last name, then (donations and pledges only) the display name if the first and last name find no contact. An anonymous gift's display name is never used, so an anonymous gift with no first or last name gets its own contact. One matching contact links the row. Two or more flag the row, and processing refuses it until you set its contact_id. A name that is a placeholder rather than a person — any word of it is "Anonymous" or "Anon", in any capitalization — is never matched: the row is flagged "Name looks anonymous" and gets its own contact, even when other rows in the batch carry the same placeholder.
• Contact, organization, household rows with a filled email: the import looks for an existing record in your organization whose primary email matches. If found, the row is treated as an update to that record at process time instead of a new create.

These lookups happen once, at upload. They do not run again later.

Stage 2 — Process (within-batch collapse only)

When you click Process Batch, the system creates or updates records according to what the upload decided. It does not re-check the system for matching emails. This is intentional — it means:

• If you upload a CSV, then add a matching contact through the CauseVox UI, then click Process, the CSV will create a new contact rather than linking to the one you just added. (The dedup suggestion system will flag them for merge after processing.)
• Two people with the same email address in your existing data will be respected — the batch is not allowed to silently override which one a donation gets linked to between upload and process.

Within a single batch, rows that share an email and have no matching existing record collapse to a single new record:

• Donations / pledges / tickets: the first row with a given email creates the new contact. Rows 2..N in the same batch link to that contact. The name, address, and other contact fields from rows 2..N are not applied — only the donation/ticket fields matter.
• Contacts / organizations / households: the first row creates the record. Rows 2..N update the same record in place — later rows' fields overwrite earlier ones.

You'll see a warning in the review screen for every row that shares an email with an earlier row:

"Linked to same email as row 3 (no existing contact found in this organization). Name, address, and other contact fields from this row will not be applied."

Rows matched by name collapse the same way: rows that share a name with no existing contact all link to the one contact created for the first of them, and each later row gets a warning.

Rows that are refused

Some rows are flagged at upload and refused when the batch is processed. A refused row is marked with an error, and the rest of the batch still processes:

• A donation, pledge or installment that names both a contact and an organization. Keep one, and add the other as a soft credit (for a donation, also possible afterwards in a Credits batch).
• A name that matches two or more existing contacts, until you set contact_id.
• An organization reference that doesn't exist yet. Import the organization first, or put it in the same batch. Large batches are processed in parallel, so a row can run before an organization in the same batch is saved; click Resume batch once the batch finishes and those rows go through.
• A row that names a contact, organization or household (contact_id, crm_organization_id, crm_household_id) by a reference ID that more than one record in your organization has. The row is refused until you use that record's CauseVox ID instead. A shared contact or organization reference is flagged at upload; a shared household reference is only caught when the batch is processed.
• A row whose own reference_id is already on more than one record of its kind in your organization (two donations, two contacts, and so on). The row can't tell which one to update, so it's refused when the batch is processed and neither record changes. This one is not flagged at upload.
• A contact naming a household (crm_household_id) that isn't in your organization. This one is not flagged at upload — it's refused when the batch is processed. Import the household first, or put it in the same batch and click Resume batch once the batch finishes.
• A relationship (on the Relationships tab of a contact batch) whose other contact isn't found, whose type isn't in your relationship list and has no reciprocal type, whose date can't be read as a date, that links a contact to itself, or whose reciprocal side already belongs to another relationship between the two contacts. Only the relationship is refused — its contact still imports. If the other contact is in the same batch but its own row failed, fix that row, then click Resume batch once the batch finishes. See Relationships in a Batch.
• An amount that isn't greater than 0. At upload, a donation or pledge amount that can't be read (like $1,200.00) is cleared and flagged, and the batch can't be processed until you fix it. An installment amount is read as a plain number: a row whose amount reads as 0 or less (including $100) is refused at upload and never reaches the batch, and digits after a comma are dropped (1,200.00 reads as 1) — remove currency symbols and thousands separators first.

A row whose payment method isn't one of your organization's payment methods is refused at upload and never reaches the batch.

Using reference_id for deterministic matching

If you want row-level control over matching (not email-based), use reference_id. That field is checked at process time for every type, and a match updates the existing record — unless the existing record has a different email than the row, in which case the row is refused ("Reference ID already belongs to a different person"), or the reference is already on more than one record, which is refused too:

• Donations, pledges, installments: reference_id is the primary matching key. Emails are only used for auto-populating contact_id when not provided.
• Contacts, organizations, households: reference_id is checked first. If it matches, primary-email matching is skipped entirely.

This is the recommended approach when syncing with an external system — your system's IDs as reference_id means re-imports are idempotent.

Matching contacts on their CauseVox ID

Contacts have one extra option, ahead of everything above: cv_contact_id, the contact's ID in CauseVox as it appears in a report export. Full precedence for a contact row is cv_contact_id → reference_id → primary email → create new.

Reach for it when contacts have no reference ID and no email to match on — anyone created by a donation form, for example — so that an export → edit → re-import round trip updates them instead of duplicating them. An ID that doesn't belong to your organization, or doesn't exist, is cleared and the row is flagged for review before you process. See Matching on the CauseVox Contact ID.

---

Donation Field Reference

These are the fields you map your columns to on the mapping screen:

Required Fields

Field	Description	Example
display_name	Public name for the donation	John Smith
amount	Donation amount (numbers only, greater than 0)	100.00
currency_code	3-letter currency code, imported as given even if it differs from the campaign's	USD
created_at	Date of donation	2024-01-15
campaign_id	Campaign GUID	abc123-def456-...

Donor Information

Field	Description	Example
first_name	Donor's first name	John
last_name	Donor's last name	Smith
email	Email address	john@example.com

Address Fields

Field	Description	Example
line1	Street address line 1	123 Main St
line2	Street address line 2	Suite 100
city	City	New York
state	State/province	NY
zipcode	ZIP/postal code	10001
country	Country	United States

Association Fields

Field	Description	Example
contact_id	Link to existing contact (GUID)	abc123-...
crm_organization_id	The donor organization, by GUID or its reference ID. Don't combine with contact_id.	abc123-...
donation_form_id	Associated donation form (GUID)	abc123-...
site_id	Associated site page (GUID)	abc123-...
project_id	Associated personal page (GUID)	abc123-...
team_id	Associated team page (GUID)	abc123-...
network_id	Associated network page (GUID)	abc123-...

Other Fields

Field	Description	Example
reference_id	Unique ID for matching/updates	DON-2024-001
comment	Donor comment	Thank you!
anonymous	Hide name publicly (true/false)	false
anonymous_type	What to hide: name, amount, or both (anything else becomes name)	name

Using Reference ID for Updates

When a record with matching reference_id exists:

• Updated: Core fields (amount, dates, donor info, etc.), revenue payment fields (status, method, channel, reference, notes), tags (additive), and custom field values (replaced)
• Not updated: Revenue splits, revenue credits, revenue solicitors, and tribute soft credits are only created on initial import. Add or correct credits on donations already imported with a Credits batch

Use reference IDs to safely re-import corrected data without creating duplicates.

Tribute Fields

Field	Description	Example
tribute_type	Type of tribute: honor or memory	honor
tribute_honoree_name	Name of honoree	Jane Doe
tribute_contact_id	Honoree's contact (GUID)	abc123-...

Revenue Fields

Field	Description	Example
revenue_status	Payment status: completed, pending, failed, refunded, partial_refunded, or chargeback. A row with any other value is refused at upload and never reaches the batch.	completed
revenue_payment_method	How it was paid — one of your organization's payment methods, by value or label (defaults: none, cash, check, credit_card, debit_card, paypal, crypto, bank_transfer, gift_in_kind, other)	check
revenue_payment_channel	Online or offline	offline
revenue_payment_reference	Check number, wire reference, receipt number	1234
revenue_payment_meta	Additional payment notes	Received via mail
fund_id	Fund allocation (GUID)	abc123-...
fund_amount	Amount to allocate to the fund	100.00

Revenue Splits (numbered, via column mapping)

Field	Description	Example
revenue_split_fund_id_1	Fund ID for the first split	abc123-...
revenue_split_amount_1	Amount for the first split	150.00
revenue_split_fund_id_2	Fund ID for the second split	def456-...
revenue_split_amount_2	Amount for the second split	100.00

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

Revenue Credits (numbered, via column mapping)

Field	Description	Example
revenue_credit_contact_id_1	Contact ID for the first credit	abc123-...
revenue_credit_crm_organization_id_1	CRM organization ID for the first credit (a credit needs a contact or an organization)	def456-...
revenue_credit_amount_1	Credit amount	250.00
revenue_credit_type_1	soft or hard. Blank means soft	soft
revenue_credit_category_1	Category: tribute, matching, solicitor, household, or other	solicitor

Add more numbered sets (_2, _3, etc.) as needed. A type or category outside these lists is refused when you upload (capitals don't matter).

Revenue Solicitors (numbered, via column mapping)

Field	Description	Example
revenue_solicitor_contact_id_1	Contact ID for the first solicitor	abc123-...
revenue_solicitor_crm_organization_id_1	CRM organization ID for the first solicitor (a solicitor needs a contact or an organization)	def456-...
revenue_solicitor_amount_1	Attributed amount	250.00

Add more numbered sets (_2, _3, etc.) as needed.

Custom Fields (numbered, via column mapping)

Field	Description	Example
donation_custom_field_1	Value for the first donation custom field	value1
revenue_custom_field_1	Value for the first revenue custom field	value1

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

Tags (numbered, via column mapping)

Field	Description	Example
donation_tag_1	Tag name for the donation	Tag A
revenue_tag_1	Tag name for the revenue record	Tag C

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

---

Pledge Field Reference

Required Fields

Field	Description	Example
display_name	Public name	John Smith
total_amount	Full pledge amount, greater than 0	1200.00
currency_code	3-letter currency code, imported as given even if it differs from the campaign's	USD
period	Number of installments, a whole number greater than 0	12
interval	Frequency: monthly or yearly. Any other value is imported as monthly without a warning.	monthly
start_date	First payment date	2024-01-15
created_at	Pledge creation date	2024-01-10
campaign_id	Campaign GUID	abc123-...

Donor Information

Field	Description	Example
first_name	Donor's first name	John
last_name	Donor's last name	Smith
email	Email address	john@example.com

Address Fields

Field	Description	Example
line1	Street address line 1	123 Main St
line2	Street address line 2	Apt 4B
city	City	Springfield
state	State/province	IL
zipcode	ZIP/postal code	62701
country	Country	United States

Other Fields

Field	Description	Example
kind	pledge, grant, or invoice (capitalization doesn't matter; defaults to pledge). A row with any other value is refused at upload.	grant
reference_id	Unique ID for matching/updates	REF-001
comment	Donor comment	Monthly pledge
anonymous	Hide name publicly (0/1)	0
anonymous_type	What to hide: name, amount, or both	name

Using Reference ID for Updates

When a pledge with matching reference_id exists:

• Updated: Core fields (amount, dates, donor info, etc.), expected revenue payment fields, tags (additive), and custom field values (replaced)
• Not updated: Expected revenue splits, expected revenue credits, expected revenue solicitors, and tribute soft credits are only created on initial import

Association Fields

Field	Description	Example
contact_id	Link to existing contact (GUID)	abc123-...
crm_organization_id	The donor organization, by GUID or its reference ID. Don't combine with contact_id.	abc123-...
donation_form_id	Associated donation form (GUID)	abc123-...
site_id	Associated site page (GUID)	abc123-...
project_id	Associated personal page (GUID)	abc123-...
team_id	Associated team page (GUID)	abc123-...
network_id	Associated network page (GUID)	abc123-...

Tribute Fields

Field	Description	Example
tribute_type	Type of tribute: honor or memory	memory
tribute_honoree_name	Name of honoree	Robert Johnson
tribute_contact_id	Honoree's contact (GUID)	abc123-...

Expected Revenue Fields

Field	Description	Example
expected_revenue_status	Payment status (pending, completed, partial, voided)	pending
expected_revenue_payment_method	Expected payment method — one of your organization's payment methods, by value or label (defaults: none, cash, check, credit_card, debit_card, paypal, crypto, bank_transfer, gift_in_kind, other)	check
expected_revenue_payment_channel	Online or offline	offline
expected_revenue_payment_reference	Check number, wire reference, receipt number	1234
expected_revenue_payment_meta	Additional payment notes	Pledged at gala
fund_id	Fund allocation (GUID)	abc123-...
fund_amount	Amount to allocate to the fund	1200.00

Expected Revenue Splits (numbered, via column mapping)

Field	Description	Example
expected_revenue_split_fund_id_1	Fund ID for the first split	abc123-...
expected_revenue_split_amount_1	Amount for the first split	500.00
expected_revenue_split_fund_id_2	Fund ID for the second split	def456-...
expected_revenue_split_amount_2	Amount for the second split	700.00

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

Expected Revenue Credits (numbered, via column mapping)

Field	Description	Example
expected_revenue_credit_contact_id_1	Contact ID for the first credit	abc123-...
expected_revenue_credit_crm_organization_id_1	CRM organization ID for the first credit (a credit needs a contact or an organization)	def456-...
expected_revenue_credit_amount_1	Credit amount	600.00
expected_revenue_credit_type_1	soft or hard. Blank means soft	soft
expected_revenue_credit_category_1	Category: tribute, matching, solicitor, household, or other	solicitor

Add more numbered sets (_2, _3, etc.) as needed. A type or category outside these lists is refused when you upload (capitals don't matter).

Expected Revenue Solicitors (numbered, via column mapping)

Field	Description	Example
expected_revenue_solicitor_contact_id_1	Contact ID for the first solicitor	abc123-...
expected_revenue_solicitor_crm_organization_id_1	CRM organization ID for the first solicitor (a solicitor needs a contact or an organization)	def456-...
expected_revenue_solicitor_amount_1	Attributed amount	600.00

Add more numbered sets (_2, _3, etc.) as needed.

Custom Fields (numbered, via column mapping)

Field	Description	Example
pledge_custom_field_1	Value for the first pledge custom field	value1
expected_revenue_custom_field_1	Value for the first expected revenue custom field	value1

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

Tags (numbered, via column mapping)

Field	Description	Example
installment_profile_tag_1	Tag name for the pledge	Tag A
expected_revenue_tag_1	Tag name for the expected revenue record	Tag C

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

---

Installment Field Reference

Required Fields

Field	Description	Example
installment_profile_id	Pledge profile GUID	abc123-def456-...
amount	Payment amount (numbers only)	100.00
created_at	Date of payment	2024-01-15

Optional Fields

Field	Description	Example
invoice_id	Link to scheduled invoice (GUID)	abc123-...
reference_id	Unique ID for matching/updates	PAY-2024-001
display_name, first_name, last_name, email	Payer details. Leave blank to use the pledge's donor. An email that belongs to an existing contact makes that contact the payer — except on a pledge whose donor is an organization	Jane Smith
contact_id / crm_organization_id	The payer, if different from the pledge's donor (one or the other)	abc123-...

Using Reference ID for Updates

When an installment with matching reference_id exists:

• Updated: Core fields (amount, date, etc.), revenue payment fields (status, method, channel, reference, notes), tags (additive), and custom field values (replaced)
• Not updated: Revenue splits, revenue credits, and revenue solicitors are only created on initial import

Revenue Fields

Field	Description	Example
revenue_status	Payment status: completed, pending, failed, refunded, partial_refunded, or chargeback. A row with any other value is refused at upload and never reaches the batch.	completed
revenue_payment_method	Payment method — one of your organization's payment methods, by value or label (defaults: none, cash, check, credit_card, debit_card, paypal, crypto, bank_transfer, gift_in_kind, other)	check
revenue_payment_channel	Online or offline	offline
revenue_payment_reference	Check number, wire reference	1234
revenue_payment_meta	Additional payment notes	Received via mail
fund_id	Fund allocation (GUID)	abc123-...
fund_amount	Amount to allocate to fund	100.00

Custom Fields (numbered, via column mapping)

Field	Description	Example
installment_custom_field_1	Value for the first installment custom field	value1
revenue_custom_field_1	Value for the first revenue custom field	value1

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

Revenue Splits (numbered, via column mapping)

Field	Description	Example
revenue_split_fund_id_1	Fund ID for the first split	abc123-...
revenue_split_amount_1	Amount for the first split	60.00

Add more numbered pairs (_2, _3, etc.) as needed.

Revenue Credits (numbered, via column mapping)

Field	Description	Example
revenue_credit_contact_id_1	Contact ID for the first credit	abc123-...
revenue_credit_crm_organization_id_1	CRM organization ID for the first credit (a credit needs a contact or an organization)	def456-...
revenue_credit_amount_1	Credit amount	100.00
revenue_credit_type_1	soft or hard. Blank means soft	soft
revenue_credit_category_1	Category: tribute, matching, solicitor, household, or other	solicitor

Add more numbered sets (_2, _3, etc.) as needed. A type or category outside these lists is refused when you upload (capitals don't matter).

Revenue Solicitors (numbered, via column mapping)

Field	Description	Example
revenue_solicitor_contact_id_1	Contact ID for the first solicitor	abc123-...
revenue_solicitor_crm_organization_id_1	CRM organization ID for the first solicitor (a solicitor needs a contact or an organization)	def456-...
revenue_solicitor_amount_1	Attributed amount	100.00

Add more numbered sets (_2, _3, etc.) as needed.

Tags (numbered, via column mapping)

Field	Description	Example
revenue_tag_1	Tag name for the revenue record	Tag A

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

---

Contact Field Reference

Required Fields

Field	Description	Example
display_name	Contact's display name	John Smith
created_at	Creation date	2024-01-15

General Information

Field	Description	Example
reference_id	Unique ID for matching/updates	CON-2024-001
cv_contact_id	Advanced — the contact's ID in CauseVox, from a report export. Updates that exact contact.	wPk3nQ7ZmL2xR8vY

Using Reference ID for Updates

When a contact with matching cv_contact_id, reference_id, or primary email exists:

• Updated: Core fields (name, title, etc.), primary email, phone, and address (upserted), tags (additive), and custom field values (replaced)
• Only columns present in your file are applied — omit a column and the existing value is kept
• Non-primary contact methods are not affected

| title | Name prefix | Mr. | | first_name | First name | John | | middle_name | Middle name | Robert | | last_name | Last name | Smith | | suffix | Name suffix | Jr. | | maiden_name | Maiden name | Jones | | deceased | Mark as deceased (true/false) | false | | can_contact | Allow general contact (true/false) | true |

Email Fields

Field	Description	Example
email	Primary email address	john@example.com
email_can_contact	Allow email contact (true/false)	true

Association Fields

Field	Description	Example
crm_organization_id	Link to a CRM organization (GUID or reference ID). An organization not found when the batch is processed fails the row.	abc123-...
crm_organization_role	The contact's role at that organization, set when the contact is newly linked to it	Board Member
crm_household_id	Add the contact to a household (GUID or reference ID). A household not in your organization fails the row.	HH-0001

CRM Organization ID

You can use either the internal GUID or the organization's reference_id to link a contact to a CRM organization. Reference IDs are automatically resolved during import. If the organization is in the same batch, click Resume batch once the batch finishes for any row that ran before the organization was saved.

Relationship Fields (numbered, via column mapping)

Field	Description	Example
contact_relationship_contact_id_1	The other contact (GUID or reference ID), which can be in the same batch	C-1042
contact_relationship_type_1	What the other contact is to this row's contact	Parent
contact_relationship_reciprocal_type_1	What this row's contact is to the other contact. Blank fills it from your relationship list	Child
contact_relationship_start_date_1	Start date (YYYY-MM-DD)	2020-06-01
contact_relationship_end_date_1	End date (YYYY-MM-DD)	2024-01-31

Add more numbered groups (_2, _3, etc.) as needed. Write each relationship once, on either person's row. See Adding Contacts in Batch.

Phone Fields

Field	Description	Example
phone	Primary phone number	555-123-4567
phone_country_code	Country code for phone number	US
phone_can_call	Allow phone calls (true/false)	true
phone_can_text	Allow text messages (true/false)	true

Address Fields

Field	Description	Example
line1	Street address line 1	123 Main St
line2	Street address line 2	Suite 100
city	City	New York
state	State/province	NY
zipcode	ZIP/postal code	10001
country	Country	United States
address_can_contact	Allow postal mail (true/false)	true

Custom Fields (numbered, via column mapping)

Field	Description	Example
contact_custom_field_1	Value for the first contact custom field	value1

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

Tags (numbered, via column mapping)

Field	Description	Example
contact_tag_1	Tag name for the contact	Tag A

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

---

Organization Field Reference

Crediting an organization on a gift?

This section is for importing organizations as CRM records (name, address, type). To credit an organization for a donation, pledge, or installment — a revenue credit or a solicitor — use the revenue_credit_crm_organization_id_* and revenue_solicitor_crm_organization_id_* columns on the gift itself. See Donation, Pledge, and Installment revenue credits and solicitors above. For donations already in CauseVox, add the credit in a Credits batch.

Required Fields

Field	Description	Example
name	Organization name	Acme Foundation

Contact Info

Field	Description	Example
email	Primary email address	info@acmefoundation.org
phone	Primary phone number	555-100-2000

Address Fields

Field	Description	Example
line1	Street address line 1	100 Philanthropy Blvd
line2	Street address line 2	Suite 400
city	City	Boston
state	State/province	MA
zipcode	ZIP/postal code	02101
country	Country	United States

Preferences

Field	Description	Example
email_can_contact	Allow email contact (true/false)	true
phone_can_call	Allow phone calls (true/false)	true
phone_can_text	Allow text messages (true/false)	true
address_can_contact	Allow postal mail (true/false)	true

Other

Field	Description	Example
reference_id	Unique ID for matching/updates	ORG-2024-001
crm_organization_type_id	Organization type ID (GUID)	abc123-...

Custom Fields (numbered, via column mapping)

Field	Description	Example
organization_custom_field_1	Value for the first organization custom field	value1

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

Tags (numbered, via column mapping)

Field	Description	Example
organization_tag_1	Tag name for the organization	Tag A

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

---

Household Field Reference

Required Fields

Field	Description	Example
name	Household name	The Smith Family

Contact Info

Field	Description	Example
email	Primary email address	smithfamily@example.com
phone	Primary phone number	555-200-3000

Address Fields

Field	Description	Example
line1	Street address line 1	42 Oak Lane
line2	Street address line 2	Unit B
city	City	Portland
state	State/province	OR
zipcode	ZIP/postal code	97201
country	Country	United States

Preferences

Field	Description	Example
email_can_contact	Allow email contact (true/false)	true
phone_can_call	Allow phone calls (true/false)	true
phone_can_text	Allow text messages (true/false)	true
address_can_contact	Allow postal mail (true/false)	true

Other

Field	Description	Example
reference_id	Unique ID for matching/updates	HSH-2024-001

Using Reference ID for Updates

When a household with matching reference_id (or primary email) exists:

• Updated: Core fields (name, etc.), primary email, phone, and address (upserted), tags (additive), and custom field values (replaced)
• Non-primary contact methods are not affected

Use reference IDs to safely re-import corrected data without creating duplicates.

Custom Fields (numbered, via column mapping)

Field	Description	Example
household_custom_field_1	Value for the first household custom field	value1

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

Tags (numbered, via column mapping)

Field	Description	Example
household_tag_1	Tag name for the household	Tag A

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

---

Ticket Field Reference

Required Fields

Field	Description	Example
first_name	Ticket holder's first name	Jane
email	Ticket holder's email address	jane@example.com
campaign_id	Campaign ID (GUID)	abc123
ticketing_form_id	Ticketing form ID (GUID)	def456
tier_id	Ticket tier ID (GUID)	ghi789

Optional Fields

Field	Description	Example
last_name	Ticket holder's last name	Smith
status	Ticket status (defaults to "unredeemed")	unredeemed
created_at	Created date (defaults to current date)	2024-06-15
site_id	Site ID (GUID)	jkl012

Custom Fields (numbered, via column mapping)

Field	Description	Example
ticket_custom_field_1	Value for the first ticket custom field	value1

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

Tags (numbered, via column mapping)

Field	Description	Example
ticket_tag_1	Tag name for the ticket	VIP

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

---

Formatting Tips

Dates

Use ISO format for best results:

• Recommended: 2024-01-15 (YYYY-MM-DD)
• Also accepted: 01/15/2024, January 15, 2024

Custom date fields and relationship start/end dates accept only 2024-01-15 or 1/15/2024 (a four-digit year, a real day). Anything else — January 15, 2024, 1/15/24, 2/30/2024, text — is not guessed: a custom date field's value is cleared with a warning on the row, and a relationship is refused with a message saying which formats to use.

Currency Codes

Use standard 3-letter ISO codes:

• USD - US Dollar
• CAD - Canadian Dollar
• EUR - Euro
• GBP - British Pound

Boolean Fields

For true/false fields like anonymous:

• True: true, yes, 1
• False: false, no, 0

GUIDs

To get GUIDs for campaigns, contacts, etc.:

1. Go to the record in CauseVox
2. Copy the ID from the URL or details panel

---

Common Errors

"Invalid Campaign … was cleared"

The campaign_id doesn't match a campaign in your organization, so it was cleared and the row is flagged. The same happens for any other ID column (form, site, fund, contact). Check the GUID is correct and belongs to this organization, then fix the row before processing. The exception is crm_household_id: it is never cleared, and a household not in your organization fails the row when the batch is processed.

"Amount is required"

The amount column isn't mapped. A donation or pledge amount that can't be read (for example $1,200.00) is cleared and flagged instead — remove currency symbols and thousands separators.

"Invalid date format"

The date couldn't be parsed. Try using YYYY-MM-DD format.

"File too large"

Your file has more than 25,000 rows. Split it into smaller files and import each separately.

---

Best Practices

1. Test first - Import a small sample before the full file
2. Use the template - Start with our sample spreadsheet
3. Check encoding - Save CSV as UTF-8 for special characters
4. Trim whitespace - Remove leading/trailing spaces from data
5. Validate GUIDs - Double-check all ID references
6. Keep backups - Save your original file before importing