You can import data into CauseVox using a spreadsheet (CSV file) to track, manage, and report on your records over time. Batch imports support donations, pledges, installments, contacts, organizations, and more including splits, credits, tags, and custom fields.
Use the quick links to jump to the right section:
How Imports Work
Batch importing allows you to upload structured data into a selected resource (donations, contacts, pledges, etc.) using a CSV file.
Each resource includes a downloadable sample spreadsheet that provides:
Recommended column headers
Required fields
Accepted date/time formatting
Proper formatting for splits, credits, tags, and custom fields
You can:
Upload any number and combination of valid column headers (field labels)
Arrange columns in any order
Include only the fields you need
Custom Fields
Custom fields must be created globally in Account Settings before importing so they are available in the mapping dropdown.
During import, you will map the spreadsheet field label to the global custom field label it represents.
Using a contact custom field example:
First, create the contact custom field "How did you first hear about our organization?" with its values, e.g. "Website", "Friend/Family", globally as well as in the contact record settings, and then update and import your spreadsheet.
Once imported, you can manually map the column header to the custom field label. The values will auto-flow into the contact records.
Tags
Tags are also located globally in the Account Settings, however they do not need to be created ahead of time. If a tag value is included in your spreadsheet, it will automatically be created in the global settings and applied when you map to Contact Tag.
Contact Matching for Monetary Resources
For donations, pledges, installments, and other monetary records:
The system uses email address to look up an existing contact.
If a contact exists, the record will be connected.
If no contact exists, a new contact will automatically be created for each new record included in the spreadsheet.
Reference IDs
reference_id must be assigned during the initial import if you plan to update records later.
If you re-upload a batch using the same reference IDs:
Existing records will be updated
Records will not be duplicated
This allows you to safely correct errors or add missing data.
Field Grouping (Splits & Credits)
Some data types require grouping numbers to associate related columns correctly.
Grouping is required when importing:
Revenue splits
Credits (soft credits, solicitor credits, etc.)
Revenue Splits
If a donation is split across multiple funds, each split must include:
Fund ID
Fund Amount
To ensure each fund is paired with the correct amount, matching group numbers must be used during field mapping.
Example pairs:
revenue_split_fund_id_1
revenue_split_fund_amount_1
revenue_split_fund_id_2
revenue_split_fund_amount_2
Add more numbered pairs (_3, _4, etc.) as needed.
The Group # format follows the number attached to the field label, i.e. "1" or "2", etc. So "revenue_split_fund_id_1", and "revenue_split_fund_amount_1" will both be assigned Group # 1.
Credits
If assigning multiple credits to a single donation, each credit must include:
Credit Contact ID
Credit Amount
Credit Type
Credit Category
To ensure each credit is paired with the correct data, matching group numbers must be used during field mapping.
Example sets:
revenue_credit_contact_id_1
revenue_credit_amount_1
revenue_credit_type_1
revenue_credit_category_1
revenue_credit_contact_id_2
revenue_credit_amount_2
revenue_credit_type_2
revenue_credit_category_2
Add more numbered sets (_3, _4, etc.) as needed.
Grouping Is NOT Required For
Tags
Custom fields
Standard contact fields
Standard donation fields
Tags may be added as:
contact_tag_1 contact_tag_2 contact_tag_3
Each tag column adds an additional tag.
Additional Notes & Best Practices
Maximum upload size is 5000 rows per spreadsheet.
Split your data into multiple files if needed.Campaign, site, form, P2P, and fund page IDs can be found within the Manage tab. Hover over dropdown fields to reveal and copy the ID.
Custom field mapping pulls from the global custom field list for the selected resource.
Splits and credits must use consistent numbering across related columns.
You may save a column mapping configuration as a template for future imports.
Example Contact Batch Import
Step 1: Under Data select Import/Batches >> Create. You can also use the pencil icon to modify a batch that hasn't been processed.
Step 2: Select the resource from the tabs (donations, pledges, contacts, etc.), then select Import From Spreadsheet at the bottom.
Step 3: Drag and drop the CSV file to import. You’ll see a link to download a sample spreadsheet for that specific resource type.
This sample file includes:
Recommended column headers
Examples of valid values
Proper formatting for splits, credits, tags, and custom fields
With the customizable spreadsheet you can:
Upload any combination of valid column headers
Arrange columns in any order
Include only the fields you need
Pro tip: Use the linked resources to prepare your data:
To import new custom fields, add custom fields globally in the Account Settings first so they're available during mapping.
Tags do not need to be added in the global settings prior to import. The values will auto-populate by the Contact Tag field label.
Created_at dates must be in format: YYYY-MM-DD HH:MM:SS. For example: 2024-01-15 14:30:00
Step 4: The system will auto-map the columns based on the field labels (header names).
Use the Map To drop downs to manually select unmatched fields, or select Skip (do not import).
Select Continue to Preview to verify the data. Scroll right to view all columns of data. Select Back to Mapping if you need to modify the column mapping.
Pro tip: Select Save as Template to save time importing your next batch.
Step 6: Once you verify the preview, select Start Import to view the status. Here you can view requirements and import warnings, then make changes to individual line items, or choose to modify the spreadsheet and re-import.
Step 7: Once the warnings are resolved, select Process Batch to complete the import.
If you have additional questions, you can email [email protected].