The Import Utility lets administrators add and update records in VolunteerMatters in bulk by uploading a CSV file. Use it to create new contacts, update existing contacts, add credentials to contacts, and record volunteer history.

Who can use it: Administrators with the Configuration role. 

Where to find it: Configuration > Import

IMPORTANT NOTE: 

Imports cannot be reverted or undone. So proper precautions should be taken when using this utility. 

 

 

You can also view recent imports section on the main imports page which includes the last 10 imports run. This includes when the import was started, the type, the status, number of rows in the import, how many records were created, updated, skipped or failed. Additionally, it will display the administrator who ran the import (and link to their contact record). As well as allow the administrator to view and download the results and original import file. 

There is also a link to view all import history on one page.  This includes all of the information listed above. 

Please note: Downloadable files are removed after 30 days but the rest of the history information will remain. 

 

---

Import Types

---

Starting an Import
 

There are two ways to begin:

1. Select an import type from the New Import dropdown at the top of the page and select the import you wish to run, or
2. Click the Start button under the import type you want on the main Import page.

 

---

General Import Process

1. Prepare your CSV file (see Preparing Your CSV File below).
    
2. Go to Configuration > Import and start the import type you need.
    
3. Upload your CSV file.
    

4. Map the columns in your file to VolunteerMatters fields. Required fields are marked with a red *, and Validate Import Data stays unavailable until every required field is mapped.
   
   

    

5. Click the Validate Import Data button.
   
   
    
6. Review the validation results. If there are errors, the page shows "Import file verification failed" and tells you how many problems were found in how many rows (for example, "3 problems were found in 3 rows. Fix them in the file and upload it again."). Correct your file or mapping and try again.
    
7. Once validation succeeds, click the Import button to complete the import.
   
   
    
8. Click the "Are you sure?" 
   
   
    
9. The page will refresh, and will proceed with the import and display a Progress Bar as the import continues and finally completes.
   
   
   
   
   
   From here you can download and view the results or the original import file via the buttons onscreen.
    
10. Spot-check a few records to confirm the data looks as expected.

 

Column mappings are remembered

• If validation fails, click Upload New File to try again with a corrected file. Your column mappings are kept, so you don't have to start over.
• New imports start from the mappings used in your last import wherever the column headings match. Anything you choose manually always overrides a suggested mapping.
• Columns from a contact export (for example, _name.first or Home_Address.city) map automatically, so you can export contacts, edit the file, and re-import it without mapping each column by hand.

Tip

• Start with a small test batch before importing your full file.  This will help you make sure you have the process and results just how desired. 

---

Preparing Your CSV File

• Save the file as CSV and include every required column for the import type.
• Remove formulas and extra formatting before saving.
• Use consistent dates in MM/DD/YYYY format.
• Mobile numbers are checked and saved in E.164 format (for example, +19045551234). Numbers that lose the plus sign when saved from a spreadsheet (for example, 19045551234) are accepted. Other telephone fields also accept a leading 1 without the +. Numbers that can't be read as valid phone numbers are not saved.
• Confirm that any Contact IDs and Credential Integration Codes exist in your site.
• For Volunteer History, verify the project, position, and position start date values.

Templates

Import templates are available in the Importing section of the VolunteerMatters Knowledge Base:

• Contact Import (will include any active custom fields created in the system)
• Contact Update Import (will include any active custom fields created in the system)
• Credential Import
• Volunteer History Import

For Contact Updates, it may be easier to create a Contact List View with all the contacts and fields (including Contact ID and Contact Name and Email) you may be updating and then export it to use as your import file template. This will make sure you have the Contact ID or Contact Name/Email needed for mapping.

 

 

---

Contact Import

Creates new contact records.

Required fields: First Name, Last Name, Email

Notes

• Contact ID is generated automatically and cannot be supplied.

Status

• If your file has no Status column (or you don't map one): a yellow warning explains that Status isn't mapped, so all new contacts will get the status below. The Status dropdown lets you choose the status for every contact in the file. The dropdown lists your site's configured statuses, each followed by its underlying standing in parentheses, for example: Active, Banned, Exit, Hold, Hold - Mandated (HOLD), Inactive (EXIT), Not Active (EXIT). Your list will match your own site's configuration.  Note: If the status label exactly matches the standing type, no standing is shown.  
• If you map a Status column: every row must have a Status value. A blank Status cell blocks the import with the message "Status is blank". Fill in every row (or remove the Status mapping and use the dropdown instead), then upload the file again.

Validation results

• Potential duplicate contacts are identified during validation, and you choose whether to skip them or create them anyway.
• If a row can't be imported, you'll see "Import file verification failed." followed by a message such as "2 problems were found in 2 rows. Fix them in the file and upload it again." For example, a blank Status cell in a mapped Status column counts as one problem for that row. Correct the rows in your file and click Upload New File. Your column mappings are kept.

 

 

---

Contact Update Import

Updates existing contact records. This import does not create new contacts.

How rows are matched: Each row must match exactly one existing contact, using either:

• Contact ID, or
• First Name + Last Name + Email (not case-sensitive)

Notes

• Rows with no match, or with multiple matches, are skipped and reported.
• Mapped fields overwrite existing values, except the fields used for matching.
• Name fields such as Middle Name, Suffix, Title/Prefix, and Nickname can be updated.
• Tip: export a contact list view that includes Contact ID to use as your file.

Validation results

• As long as the required fields are met, the validation is completed. However, after running the import if there is a row where it is mapped by a Contact ID that doesn't exist, that row is skipped and noted: 
  
  "Skipped - No contact found for External Id."
  
  The rest of the successfully mapped rows will be updated. 

 

---

Credential Import

Adds credentials to existing contacts. The contact and the credential must already exist in the system. It does not need to be on the contact's record already but simply an active credential in the system. 

Required fields: Contact ID, Credential Integration Code, Start Date, Status, Status Date

Optional fields: Expiration Date, Issued By, Statement, Signature, Guardian Signature, Admin Notes

Notes

• To find a credential's Integration Code, go to Configuration > Credentials and open the credential.
• If Expiration Date is blank, it is calculated from the credential's configuration when applicable.
• Attachments cannot be uploaded via import.

If the contact already has the credential

• The existing credential is updated rather than a new one being created, and the row is counted as Updated instead of Created. A credential the contact doesn't have yet is created as usual.
• Anything the import doesn't cover is kept, including previously uploaded files, background check details, and the integration link.
• Start Date, Status, and Status Date always replace the existing values. So does the expiration date: either the date in your file or, if that cell is blank, the date calculated from the credential's configuration.
• A blank cell in an optional column (Issued By, Statement, Signature, Guardian Signature, Admin Notes) never overwrites the existing value.

Validation results

• No contact has this Contact ID
• No credential has this integration code

Rows with unknown references block the import until they are corrected.

 

---

Volunteer History Import

Records self-reported hours against an existing project position that allows self-reported hours. Create the project and position first.

Required fields: Contact ID, Unique Project Name, Position Name, Position Start Date, Volunteer Date, Description, Credited Hours

Notes

• Position Start Date must match the existing position exactly, since a project can have multiple positions with the same name.
• Volunteer Date must fall within the position's date range.
• If the contact is not already assigned to the position, the import creates the assignment.
• While manually adding Self-Reported hours (by admin or volunteer) is limited to 24 hours or under, the import allows any number of hours within a single self-reported hours entry.  This helps will bulk importing volunteer history without specific volunteer dates. 

Validation results

• An incorrect Project Name, Position Name, or Position Start Date is rejected during validation. A Contact ID that no contact has is rejected as well.

Note: While hours imported on a position outside the position's date range will pass verification, but like manually adding hours to a position needing to be within the position's date range, the import also requires this and any rows like this will be skipped and be noted on the import's detail page. 

 

 

---

Import History

The import history page lists your past imports. Open an import to see its job page, which includes:

• Started by: a link to the administrator's contact record who ran the import.
• Download results file: download CVS file with the results on the import per row.
• Download uploaded file: download the original CSV that was imported.

Import files are kept for 30 days, after which the download is no longer available. However, the import entry will remain. 

When an import finishes, a summary email is sent that names the import type (for example, "Contact Update").

 

---

Understanding Validation Results

Unknown references (a Contact ID, credential integration code, project name, or position name and start date that doesn't exist) block the import until fixed. If a record is deleted between validation and import, that row is skipped with a plain-language reason rather than causing an error.

---

Troubleshooting

Imports can change many records at once. Validate carefully and test with a small file first. If you run into validation errors or are unsure how to structure or map your data, contact VolunteerMatters Support.