In This Article:

    Manage Imports - Getting your data into Salsa from outside of Salsa

    In This Article:


      When To Use It

      Use Imports to put entire lists of supporters into Salsa in one go from an outside database or spreadsheet. Imports are a powerful, flexible feature. They feature heavily in the setup of most new Salsa accounts, but are also frequently useful for a variety of ongoing data management needs.

      How To Get There

      Imports begin outside of Salsa, with a data source of some kind that will need to be saved into a delimited file for import. (We'll discuss more on how to do that below.) Once there's an import-ready delimited file, navigate to the Import Supporters tool in the Supporter Package.


      Training Video

      Here's a short training video with an overview of the import process. Full feature documentation is found below.

      Preparing Your Data for Import

      The first step to importing happens outside Salsa altogether: you'll need to ready your data for import by getting it into a Salsa-friendly format.

      Formatting Your Import File

      An import file should comprise data that can be held in a single worksheet of Excel or a similar spreadsheet application.

      That spreadsheet should hold:

      • One horizontal row per supporter (or other record) to create in Salsa
      • One vertical column per field whose data will be filled in each of those records

      You probably have a lot more information than just email: first names, last names, addresses, phone numbers, and so forth. There is no maximum or minimum "width" to your import spreadsheet. 

      A Note About Preventing Duplicate Records

      By default, Salsa deduplicates based up the Email field.  This means that Salsa takes the Email field from your import and searches your existing supporter records for any identical email address. When it finds a match, it knows to update an existing record (rather than creating a new one). For this reason, you should always include Email as one of the columns in your source file.

      If you want even more assurance against duplicate records, you can add additional columns for these data points. The Salsa Import Tool seeks a data match using these three fields, in this order, if any of them are provided in the import file:

      1. supporter_KEY - A distinct ID number assigned by Salsa
      2. uid - An optional unique ID field that you can fill with values generated from an outside database
      3. Email

      No matter how much (or how little) you're importing, every column in an import spreadsheet should contain only one single piece of information. For example, First Names and Last Names need to be in two distinct columns. The same goes for addresses, which must be broken up into separate columns for Street, City, State and Zip.

      Click to enlarge

      We have a template tab-delimited text file that you can download to see how best to format your data for import into Salsa.

      Wary? If you're new to the imports feature or unsure how Salsa will render the data in your file, a good way to start might be to make a test import file comprising just the first three or four lines of your potential import. Import that test, then eyeball the resulting data before proceeding with the full file import.

      Saving Your Import File

      The last step in prepping your data is saving it to a usable format. Because Salsa cannot import directly from an Excel or OpenOffice spreadsheet, you'll need to save your data in a tab-delimited text format. Also, be sure not to include any special characters in your filename.  This process will work for most files, but if you have international characters, please use the alternate process noted below. 

      Basic process:

      1) Open your correctly formatted Excel file
      2) In the File menu, click Save As


      3) Select the Format drop down list and select Tab Delimited Text. Click .


      4) When prompted with the scary message that some features may be removed, click to convert the file anyway. This is just Excel being proprietary.


      International/Non-English Data

      Salsa can readily handle data sets that contain non-English characters. Usually, you'll just need to do one quick preparatory loop before import.

      1. Saving Your Import File with International Data

      Ensure the source import file is saved with a compatible character encoding, ideally UTF-8. Follow these steps:

      For instance, the process for generating a compatible import file for Excel is typically:

      1. Save-as a tab-delimited text file as described above.
      2. Close and then reopen the newly-saved tab-delimited text file in a plain-text application such as Notepad.
      3. Select File >  and set the  value to UTF-8.


      Basic Supporter Import

      Your import file is ready, and Salsa is ready. Now, let's do what you came to do - Import a list of supporters!

      The import tool is located in the Supporter Management tab. Click the Supporter Management tab, then click "Import Supporters" in the sub-navigation menu:

      It's just a two-step process.

      Step 1: Choose your data source

      When you've opened Salsa's import feature, you'll immediately see the first step to run an import: selecting the data file that you'll be importing.

      • Option 1:  Click the "Browse" button next to the Filename field to import a file (you'll usually use this option). This option is illustrated below.
      • Option 2:  Simply paste the data into the text area at the bottom of the page if it's a really small amount of data. This option is not recommended.

      Other step one options

      For most everyday supporter imports, choosing a file and its appropriate delimiter is all you need to do on step one. You can freely ignore the other options in this step unless you have specific reason to use them.

      • Write-In Table enables advanced users to import to Salsa data objects other than the Supporter table. (Advanced users desiring more information about each field and data type, please see here.)
      • Similar Uploads may help shortcut the second import step if you regularly import data files that look pretty similar to one another.
      • Character Encoding is important only when importing non-English data characters.

      Click  to upload the file and move on to step 2.


      Step 2: Match your spreadsheet columns to Salsa's field names

      In the second step of the import process, you tell Salsa to insert Tab A into Slot B.

      You should now see a two columns:

      1. A list of fields matching the top row of data in your import file; and,
      2. A parallel column of pull-down menus full of Salsa fields.

      Your task is simple, but incredibly important. You must match your column headers (on the left) with Salsa's field names (on the right). This ensures that your data gets stored in the correct place. You also have the option to set any column to "Ignore" to have the importer disregard it. A complete list of of the fields in Salsa's supporter table is here.


      If the second step shows you garbled data, or all your data in a single field, the importer didn't understand your file. Return to step one and try again. The most common cause of this is choosing the wrong field delimiter (e.g. tab instead of comma) in step one.

      Supporter Groups and Tags

      To add all supporters in this source file to be added to a particular group (which must exist prior to the upload), or given a particular tag, you can specify them here.


      If you want to add some supporters in this source file to one or more groups and tags, read more information about formatting groups and tags for import.

      NOTE: You may only import existing supporters against groups that they are not already assigned to unless you use this workaround

      Advanced Options

      Most regular imports can just ignore these steps.

      • Skip Lines enables you to put a number of rows in the import spreadsheet that you'd like Salsa to skip over. Often, the first line of a file will have the column names in it, instead of actual values, and it can be helpful (though not essential) to skip that one line in order to avoid create a supporter whose first name is "First Name."
      • Deduplication overrides Salsa's default deduplication logic by keying it to any supporter field -- or turning it off deduplication entirely for the current upload.
      • Overwrite Options modify Salsa's behavior when the import's deduplicator does match an incoming row to a record already in Salsa. Absent any of these settings, such a match will result in Salsa
        • Overwriting existing data with the data for a corresponding field in the import. (e.g., if the pre-existing supporter record has a First Name of "Joe" and the import has a First Name of "Joseph", "Joseph" will be the First Name in the record post-import); and
        • Ignoring null or empty values in import fields. (e.g., if the pre-existing supporter record has a First Name of "Joe" and the import has a blank value for First Name, "Joe" will be the First Name in the record post- import).

      When you're ready with field matching and any additional settings, hit the button!

      A note about e-mail subscriptions

      Salsa's baseline behavior is to assume that it's managing a list of (actual or potential) recipients of mass email blasts. If you're importing a list of people who should not receive email, include a column in your import file with the value of 0 for every row in the import. Have the importer write that column to Salsa's Receive Email field.

      What if there's a problem?

      It's easier to prevent problems than to fix them. If you're unsure of your import, take these precautionary steps first:

      1. Use the Query/Export tool to run a query of your entire supporter list and export that data to Excel. This creates a backup of data stored on the supporter table.
      2. After you finish formatting your source file, make a copy of it and delete all except a few rows in the copy. Import this copy first and spot check the data. After you've verified the data in this "mini-import," go back and import the complete file.

      Despite all of those precautions, mistakes can still happen. To help you sort out the data should this occur, Salsa automatically creates two system-generated tags for every import (where XXXXX is the unique ID number of the import):

      1. import:createdXXXXX - New records were created by the import
      2. import:updatedXXXXX - Pre-existing records which were "touched" by the import.

      Running a query on these two tags will help you identify every record which was affected by this import. If there is a problem, this list of supporter records gives you a place to start restoring your data (and a place for our support team to start helping).


      Was this article helpful?
      1 out of 1 found this helpful
      Have more questions? Submit a request


      • A warning to others that carriage returns/line feeds within a field will be interpreted as a new record. They must be removed before you import your data. Check your text file to ensure it has exactly the number of records that you had in your Excel file (remember to account for the field headings).

        Comment actions Permalink
      • Hi Dan,

        Here is how we recommend you import your contact history:

        1. Make sure all of the contacted supporters are already in Salsa. Run a query to get their supporter_KEYs and use that to create a file with the following columns:





        notes (this is optional)

        You will be importing this file into Salsa's contact_history table, whose description is: .

        1. Import your file, and match the contact_history fields to the corresponding fields in the second step of the import process. I've created this short video so you can see what the import process looks like:

        Comment actions Permalink
      • Jake, I was actually referring to the Language Code field (eng, spa, etc.). I have received the listing. Thanks.

        Comment actions Permalink
      • can you undo and import

        Comment actions Permalink
      • Hi John,

        It may be that the issue is related to importing into multiple chapters at the same time.  Our chapters specialist would be happy to take a look - can you open a support ticket and attach the file you're importing so we can take a look?


        Comment actions Permalink
      • Jay - there are various ways to 'back out' an import, depending on how it was performed. If you contact our great Support team will be able to help you out.

        Comment actions Permalink
      • Can I setup recurring import like once a week type of import?

        Comment actions Permalink
      • Is there a way to import blog posts from say Blogger?

        Comment actions Permalink
      • Per the "Importing Groups and Tags" section, I have a column called "Groups" but it's been ignored in my upload. What should that be mapped to?

        My data has three columns: chapter_Key, supporter_Key, Groups. Is the fact that I'm trying to define groups for specific chapters while I'm uploading at the org level part of the problem?

        Comment actions Permalink
      • Hi Jesse, 

        Here is how we recommend importing your blogs and their entries:

        1. Create a spreadsheet with your blogs in it. Do include the Reference name, but the others are optional:





        1. Save the file in tab-delimited text format as shown here: . You will be importing this file into Salsa's blog_entry table, whose description is here: )

        2. Create the blogs by importing to the blog table. You will need to write in the table name as shown here: .

        3. Run a report to export all of the blog KEYs for the blogs you just created. This video shows how to create and export such a report: .

        Export the results of that report.

        5.. Using the export, create a file with the following columns (all optional) to import into the blog_entry table:

        blog_KEY (the KEY for the blog with which the entry should be associated)

        Entry_Date (in the form YYYY-MM-DD)

        Display_Date (in the form (YYYY-MM-DD)




        PRIVATE_Author (Name of the person who wrote this entry)

        You will be importing this file into Salsa's blog_entry table, whose description is here: ) . This time, you will need to write in "blog_entry" as the "Write in table."

        Don't forget when importing to re-save your spreadsheet as a tab-delimited text file, NOT an .xls Excel file!

        Comment actions Permalink
      • Hi Fong,

        Recurring imports are not currently an "out of the box" Salsa feature.  If you want to create your own regular sync using Salsa's open API, check out our documentation.  We have a variety of partners who can help you create this if you need assistance.

        Salsa Sync for Salesforce is a free tool that does exactly what you're looking for, but the sync is specific to Salsa to Salesforce.


        Comment actions Permalink
      • I'd like to import to the event table and before I do I'd like to know if it's working. I've tried to import in the past and it didn't work (and I issued a ticket).  I think the issue was with the field "invited", "attended", "did not attend" etc.  Please confirm that it's working now and provide any additional info you may have on importing to events. 

        Many thanks!!

        Comment actions Permalink
      • Hi Meleneal,

        The process may be a bit difficult to lay out in writing. Can you email and we can set up a time to talk through this?

        Comment actions Permalink
      • How are you Jake,

        Can you please share with me how to import a global add on to existing data within Salsa.  I have identified a group of people by the Supporter Key in an .txt file and I would to add them to a group globally.  Tank  you

        Comment actions Permalink
      • I just did a test batch to the 'event' table and it did not work. The fields I used were Event Key, Supporter Key, and Status.  The import status said updates by deduplication occured, but it's not reflected in the supporters' profiles nor in the event details Attendees' tab.  I suspect it's still broken :(



        Comment actions Permalink
      • Melanie,

        If you can get by with the basic "Attended" status, then it's much easier to just do a standard supporter import, put those imported records into a group, and then query for that group. On the query results screen, you can then scroll down to the "petitions/actions/events" section to denote that those people attended one of your events:

        Otherwise, without looking at your data I can't guess at what may be the problem with importing to the events table. Can you please open a new ticket with to get some specific attention on this? Thanks!

        Comment actions Permalink
      • I am looking for a listing of the Language Codes or literal values that can be imported. Thanks

        Comment actions Permalink
      • Hi Charlotta,

        Please let me know if the information below is not what you're looking for:

        Salsa can handle those foreign characters -- as long as your format the data correctly before importing!

        You will want to make sure your file is saved in Excel as Unicode Text or UTF-8. (Alternately you can open a text file with a plain text editor, and when you save the file select Unicode or UTF-8 where it asks for the encoding type.)


        Comment actions Permalink
      • Is there anyway to log contacts in a batch? for instance, after a night of phonebanking that we track results for on an Excel sheet, can we format and upload that sheet in a way that will add phone contacts and any notes in the "Contact History" of multiple supporters?

        Comment actions Permalink

      Article is closed for comments.