Importing, Updating, and Exporting Contacts


To more efficiently add and edit contacts, you can use Spruce's bulk import/export feature. Please note that you can only perform bulk upload actions from the web, so please make sure you are logged into your account at 

Importing New Contacts

To bulk import a CSV list of contacts, first log into your Spruce account on the web.

  1. Navigate to the Contacts tab. 
  2. Select "Import Contacts" on the right side of your screen. Once you select that button, you'll be taken to a pop-up window with instructions on how to import a list of new contacts.
  3. On the screen, you'll see a downloadable template titled "Contact Template spreadsheet." Select that and you'll be taken to a page with a sample spreadsheet with the required headers for uploading new contacts into Spruce.
  4. Fill out the spreadsheet with the new contacts you'd like to upload and the relevant fields mapped to each column. 
  5. Export the changes as a new CSV to your computer. You do this by, selecting "File," on the spreadsheet, then scrolling down to "Download" and then selecting "Comma Separated Values (.CSV)."
  6. Return to the "Import Contacts" screen and either select the CSV from your files or drag & drop the CSV onto the screen. 

Your final step before selecting "Import" is to decide if you'd like to also auto-apply a tag to all these new contacts. If so, select an existing tag or create a new tag from the "Tags" option of the screen. Once you're finished, select "Import" and the new contacts will appear loaded into your Contact List.

Please note: If you want to create a new custom contact field for the contacts you're uploading (e.g., location, insurance carrier, EHR link, etc), you can do so. Notice that the last column of the sample spreadsheet contains the title "Field|<Field_Name>." You can use that column to add a new custom field to the list of contacts you're uploading. That new field will then appear as a custom field on their Contact. When you edit the title of that column, you should replace the "<Field_Name>" portion with what you'd like the custom field's name to be. For example, if you want to create a field for what insurance that list of patients has, the title of the column should be "Field|<Insurance>". You can create as many new custom fields as you'd like by following that format.

If you need to transfer contacts from your iPhone to a CSV file, review this article to learn how.

Required fields for uploading a CSV of contacts:

To protect the integrity of your contact list and avoid duplicates, when you're uploading a CSV to Spruce, we require at least one of following fields to be present or the upload will fail: First Name; Last Name; Company; Entity_ID (relevant for updating contacts, see section below).

Trouble-shooting CSV Upload Errors

Please be aware that your CSV file cannot contain special characters. Special characters such as comma (,) quotation mark, and a new line character may cause issues with a CSV import. If you get an import error, open the CSV file in Excel and use the Find & Replace tool to change or remove these specific special characters. Then retry the import. Hidden non UTF8 characters will also cause an upload failure; please ensure that the data entered into the template CSV file is clean.

Please use our downloadable template as incorrect formatting may cause upload errors.

There is a 20,000 row limit; contact lists greater than 20,000 should be split into multiple CSV files.

For customers moving contacts from one Spruce account to another, please note that if you export contacts out of one account and are trying to upload them into the other, you need to delete the "key" column before uploading the contacts into the other account. The "key" column contains a Spruce ID that represents patients in the first account. The system will silently fail because it does not find those contacts in your new account. This column is relevant when updating contacts within the same account (see following section).

Updating Existing Contacts

To update existing contacts via CSV upload, navigate to the Contacts tab on the web. Then, follow the steps in the Exporting Contacts section below to export a CSV of your existing contacts. Once you export and download the CSV, open up the spreadsheet.

On the downloaded spreadsheet, you should see all of your contacts and their associated fields. If you would like to update certain fields in the contact, just edit it directly in the sheet. To add an entirely new field, you can follow the instructions in the previous section on how to do so.

When you have finished editing the contacts, download your spreadsheet as a CSV and then follow the instructions above to import them back into your Spruce Contact List.

Please note: When editing your contacts in the spreadsheet, please do not edit anything within the column titled "key." These identifiers are used by our system to match up the old contacts with the new import, and by changing them you will incorrectly associate contact information with the wrong contact.

Exporting Contacts

To export a list of contacts and their associated fields as a CSV:

  1. Navigate to your Contacts tab on your computer/web version of Spruce.
  2. Then, select the contacts which you'd like to export by hovering over the circle icon to the left of their name and selecting to add a check next to the name.
  3. To select all of your contacts in a particular list, select the checkbox at the top of the listed contacts (next to the "Name" field). 
  4. Select the export icon (looks like an upward arrow) and select "Continue" to start the export process. The export icon will only show up when you have selected at least one contact. 
  5. Navigate to the "Activity Reports" tab of your Settings to download the CSV file.

Still need help? Contact Us Contact Us