Appearance
Importing from Spreadsheet
Upload a CSV or Excel file to add multiple donations, pledges, contacts, households, organizations, or tickets at once. This is the fastest way to import large amounts of data.
Before You Start
- Get the sample spreadsheet - Download our template to ensure correct formatting
- Prepare your data - Match your columns to our field names
- Check your limits - Maximum 15,000 rows per file
Step-by-Step Import
Step 1: Open the Import Dialog
- Create or open a batch
- 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, .xls)
Step 3: Map Your Columns
If your column headers don't exactly match our field names, you'll see a mapping screen:
- For each field, select the matching column from your file
- Leave unmapped fields blank if not used
- 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_idbut a filledemail: 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. - 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 / installments / 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."
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 always updates the existing record:
- Donations, pledges, installments:
reference_idis the primary matching key. Emails are only used for auto-populatingcontact_idwhen not provided. - Contacts, organizations, households:
reference_idis 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.
Donation Field Reference
Your column headers should match these field names exactly (case-sensitive):
Required Fields
| Field | Description | Example |
|---|---|---|
display_name | Public name for the donation | John Smith |
amount | Donation amount (numbers only) | 100.00 |
currency_code | 3-letter currency code | 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 | Link to existing CRM organization (GUID) | 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 | How to display if anonymous | Anonymous |
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, and tribute soft credits are only created on initial import
Use reference IDs to safely re-import corrected data without creating duplicates.
Tribute Fields
| Field | Description | Example |
|---|---|---|
tribute_type | Type of tribute | in_honor_of |
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 (pending, completed, voided, refunded, partial) | completed |
revenue_payment_method | How it was paid (none, cash, check, bank_transfer, credit_card, 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_amount_1 | Credit amount | 250.00 |
revenue_credit_type_1 | soft or hard | soft |
revenue_credit_category_1 | Category: tribute, matching, solicitor, household, or other | solicitor |
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 | 1200.00 |
currency_code | 3-letter currency code | USD |
period | Number of installments | 12 |
interval | Frequency (monthly/yearly) | 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 |
|---|---|---|
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, 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 | Link to existing CRM organization (GUID) | 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 (none, cash, check, bank_transfer, credit_card, 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_amount_1 | Credit amount | 600.00 |
expected_revenue_credit_type_1 | soft or hard | soft |
expected_revenue_credit_category_1 | Category: tribute, matching, solicitor, household, or other | solicitor |
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 |
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 and revenue credits are only created on initial import
Revenue Fields
| Field | Description | Example |
|---|---|---|
revenue_status | Payment status (pending, completed, voided, refunded) | completed |
revenue_payment_method | Payment method (none, cash, check, bank_transfer, credit_card, 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_amount_1 | Credit amount | 100.00 |
revenue_credit_type_1 | soft or hard | soft |
revenue_credit_category_1 | Category: tribute, matching, solicitor, household, or other | solicitor |
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 |
Using Reference ID for Updates
When a contact with matching 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)
- 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) | abc123-... |
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.
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
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
Currency Codes
Use standard 3-letter ISO codes:
USD- US DollarCAD- Canadian DollarEUR- EuroGBP- 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.:
- Go to the record in CauseVox
- Copy the ID from the URL or details panel
Common Errors
"Invalid Campaign ID"
The campaign_id doesn't match any campaign. Check:
- The GUID is correct
- The campaign exists and is accessible
"Amount is required"
The amount field is empty or contains non-numeric characters. Ensure:
- The field has a value for every row
- No currency symbols ($, €) in the amount
"Invalid date format"
The date couldn't be parsed. Try using YYYY-MM-DD format.
"Maximum rows exceeded"
Your file has more than 15,000 rows. Split it into smaller files.
Best Practices
- Test first - Import a small sample before the full file
- Use the template - Start with our sample spreadsheet
- Check encoding - Save CSV as UTF-8 for special characters
- Trim whitespace - Remove leading/trailing spaces from data
- Validate GUIDs - Double-check all ID references
- Keep backups - Save your original file before importing