Importing, Updating, and Exporting Contacts

IN THIS ARTICLE

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 app.sprucehealth.com. 

Importing New Contacts

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

Templates to get you started

You will need to create a CSV file containing all the contacts that you'd like to import. Here's a list of templates to get you started:

Instructions

  1. Navigate to the Contacts tab. 
  2. At the top of your screen next to "Invite Patient" select "More" and then select "Import Contacts". 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 link titled "Contact Template." Select that and you'll be taken to a page with a example spreadsheet with the example headers for uploading new contacts into Spruce. You can download this spreadsheet as a csv, Microsoft Excel document or even save a copy of the Google Spreadsheet to your own google docs account. 
  4. Fill out the spreadsheet with the new contacts you'd like to upload and the relevant fields mapped to each column. 
  5. Should you want to add tags please separate them by commas.
  6. Export the changes as a new CSV to your computer. 
  7. Return to the "Import Contacts" screen and click "Select File" either the CSV from your files or you can drag & drop the CSV file 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. This can be helpful should you want to add a date or tag that will signify this upload. Reminder you can then create contact filters based on these tags, read more here

How to specify tags

You can specify a list of contact tags for each contact in the "Tags" column. If there are multiple tags, specify them as comma separated values within the Tags column. So if you want to specify 3 tags, you'd do so as follows in the tag column "TagA,TagB,TagC".

How to specify custom fields

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 by specifying as many columns in the spreadsheet as there are unique custom fields. Each custom field's name should be specified as a new column header in the following format: "Field|FieldName". The "Field|" prefix tells the system that you are specifying a new custom field name. The corresponding row should contain the value for the custom field. You can specify as many custom fields as you want, and you can leave the value blank if the custom field does not apply to a particular contact.

Transferring contacts from your iPhone

This external article goes into detail for how you can transfer contacts from your iPhone to a CSV file in order to bulk import them into Spruce.

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.

Troubleshooting CSV Upload Errors

  • Please use our downloadable templates above 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).


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 Contacts" button and select "Continue" to start the export process. Note that the export button 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 exported files. Note that it, depending on the size of your export, it can take a while for the export to be available for download. You'll see a loading indicator on the activity reports until the download is available.

Structure of exported contacts

An exported list of contacts is packaged into a zipped (compressed) folder containing the following files:

  • entites.csv - This file contains the Spruce Contact ID (referred to as they "key" column), first/last/middle names, gender, tags, date of birth and category information. If you are using Hint/Elation integrations, then this file will also contain the Hint and Elation ID mappings to the Spruce contacts.
  • contacts.csv - This file contains the Spruce Contact ID (referred to as the "key" column), contact value (email address, phone number or fax number), contact label, contact type (email, phone, fax). If a contact has 2 phone numbers and 3 email addresses, then there will be 5 entries corresponding to the contact.
  • custom_fields.csv - This file contains the Spruce ContactID (referred to as the "key" column), custom field name, and custom field value. If a contact has 3 custom fields, then there will be 3 rows to fully describe the custom fields for the contact.

Click on the links to learn more on how to unzip files on Windows and Mac.


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 above to create an export of your contacts. 

Currently, we only support adding tags (not removing tags) and updating custom fields via the bulk update mechanism described.

Use the entities.csv file to specify any tags to add. Use the custom_fields.csv to make the appropriate modifications to the existing custom fields or specify new ones to add by creating a new entry for a contact, identified by the "key" column. 

When you have finished making the appropriate changes, download your spreadsheet as a CSV and then follow the instructions above to import them back into your Spruce Contact List. Note that the only columns that matter in the entities.csv file are the "key" and "tags" columns since we are only adding tags. You can delete or ignore the rest of the columns when re-importing your csv into Spruce.

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.

Still need help? Contact Us Contact Us