Spruce supports bulk import of patient and contact lists via CSV, letting you populate your contacts without manual entry. You can also update existing contact records in bulk and export your full contact list for backup or reporting. This is especially useful when transitioning from another system or onboarding a new practice. 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.
IN THIS ARTICLE
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 that contains all of the contacts that you would like to import. Get started by downloading the template for this in whichever format is most convenient for you:
- Google spreadsheet template
- CSV template
- Microsoft excel template (Click on File Download to save as an excel document)
Template completion instructions
Fill in the contact template by specifying one contact per row, with the first row reserved for column names. Every field is optional for a given contact, but you must provide at least one of the following fields for each contact: first name, last name, company name, a phone number, a fax number, or an email address. For each field, you can only have one piece of information per row.
Every field can contain whatever text you would like, with the following constraints:
| Field Name | Field Constraints |
| Each email must be a valid email address | |
| Phone | Each phone number must be a 10-digit number (acceptable formats include: (234) 567-8901, 1 (234) 567-8901, 2345678901, +12345678901) |
| Fax | Each fax number must be a 10-digit number |
| Birthday | Birthday (date of birth) must be in the form of mm/dd/yyyy (e.g., 03/15/1975) |
| Category | Category must be either "patient" or "professional" (without the quotation marks). Please note that this field controls whether Spruce will consider this contact to be a patient or a professional connection (e.g., another healthcare provider). If something else is listed in this column, the contact will still be uploaded but it will be automatically uploaded with "patient" as the category. |
| Tags | Each tag name may contain only letters, numbers, and the underscore character ("_"). Letters may be uppercase or lowercase, but they must be limited to the 26 letters of the Latin alphabet, with no accent marks or other diacritical marks. Punctuation is not allowed, except for the comma character, as it is used to separate one tag from another in this field. |
You can use the "Tags" column to specify a list of contact tags for each contact. If there is more than one tag for a given contact, separate each tag name with a comma. So if you wanted to specify three tags for a contact, you would do so as follows, in the Tags column: "TagA,TagB,TagC".
You may wish to specify multiple fields for certain types of information, such as recording both a "home" phone number and a "mobile" phone number for some or all of your contacts. Spruce supports this for phone numbers, fax numbers, email addresses, and custom fields. When dealing with any of these four types of information, you must name each column in a specific way, as follows, respectively:
- phone|name
- fax|name
- email|name
- field|name
In each of these cases, the first part of the column name (e.g., "phone|") tells the system what type of information to expect in the column. The second part of the column name will be used as the label for that information in Spruce. So a column named "phone|home" would be used to populate an optional "home" phone number for each contact. These labels can use any characters, except for the pipe character, '|'.
You may create columns for as many phone numbers, fax numbers, email addresses, and custom fields as you would like, and you may leave each of them blank for any contact that does not need them. Note in particular that custom fields (i.e., columns with names that start with "field|") may be particularly useful for storing data such as a patient's insurance information or a link to their record in an EHR.
Contact list upload instructions
When you have completed the contact template, you can upload it to Spruce to import your contacts in bulk.
- Navigate to the Contacts tab.
- 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.
- 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.
- Fill out the spreadsheet with the new contacts you'd like to upload and the relevant fields mapped to each column.
- Should you want to add tags please separate them by commas.
- Export the changes as a new CSV to your computer.
- 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 field of each contact 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. These custom fields can be free-form text fields and can hold up to 60,000 characters.
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, Phone Number, Email, or Fax.
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:
- Navigate to your Contacts tab on your computer/web version of Spruce.
- 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.
- 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).
- 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.
- 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.
Frequently Asked Questions
How do I import contacts into Spruce?
Download the Spruce CSV template, populate it with your contact data, and upload it via the Contacts import tool in settings.
Can I update existing contacts in Spruce in bulk?
Yes, this requires exporting a group of current contacts, making changes in a spreadsheet and re-uploading that list.
How do I export my contact list from Spruce?
Go to your Contacts settings and use the Export option to download your full contact list as a CSV file.