How to Import Your List

While some Gardens come pre-loaded with Voter File data, you might need to import some data into your Garden manually.

Jump to:

• Import File Requirements
• Import a New CSV
  • Selecting Your Import Type
    • Create list from Unique Identifiers
    • Update Data
    • Insert Data
  • Uploading Your New List
  • Mapping Your Columns
  • Error Handling
    • Errors from Validation Check
    • Errors from Records that Failed to Import
• Canceling an Import

Before you begin, make sure to review our Import File Requirements so your file is formatted properly before importing.

Import File Requirements

• Your file name cannot exceed 80 characters. 
• Your import cannot be larger than 60 MB. 
• Your file must be a .CSV file with UTF-8 encoding. 
  • Use plain .CSV files or MS-DOC .CSV files for importing.  Apple/Mac .CSV files are not supported. Instead follow the steps below to use Excel or Google Sheets. 
  • For Excel - File > Save as > File Format > CSV UTF-8 (comma delimited) (.csv)
  • For Google Sheets - Downloading your file from Google Docs in .csv format will automatically save to UTF-8. File > Download > Comma Separated Values (.csv)
• If you include a phone number in your import, remove the country code (+1 for the United States) from your file before importing. Imports using phone numbers that contain a country code will fail. 
• If you include a column for sex, the input must be one of the following case-sensitive values:
  • Female
  • Male
  • Non-Binary
  • Unknown
• It takes approximately 20 minutes to load every 10,000 addresses for longitude and latitude
• Apartment numbers are recommended to be listed as Address 2 
• Any addresses in your file must be in the state your Garden was created with.
   

✏️ Please Note: Your file will fail if it doesn’t meet the requirements outlined above. 

Import a New CSV

You’ll find the Imports page by clicking on the Burger Bar menu and then on Imports. 

This page is where you can see records of all your previous Imports, start the Import process with a new file, check the progress of any running Imports, and cancel Imports that are still in progress.

✏️ Please Note: Admin II & Superadmin level Users can see all the Imports in a Garden, including those from other Users.

Click on Import a New CSV.

Selecting Your Import Type

You will then need to select the type of Import you want to create. This will be determined by what you need to do with the Imported List and will also impact what fields you need in your file to Import successfully. 

Create list from Unique Identifiers 

This option allows you to create a List in OpenField using just a Unique ID. You must map at least one Unique ID from the list below. Any person in your file with an ID that matches one in your database will be added to the List.

Available Unique IDs to match on include: 

• Openfield ID
• DWID + State
• Voterbase ID
• Actionkit ID
• Van ID + State
• Action Network ID
• Mobilize ID
• State File ID + State

✏️ Please Note: You can only match on one type of Unique ID at a time.

✏️ Please Note: If you map additional columns in your file (such as name, address, etc.), the data in your file will overwrite the data currently in OpenField.

 

Update Data 

This option will require both a Unique ID from the list above and at least one other field, such as address, phone number, etc.

✏️ Please Note: You can only match on one type of Unique ID at a time. 

✏️ Please Note: Any other fields you map in your file will overwrite the data currently in OpenField. 

✏️ Please Note: We suggest you only use this option if you are certain the data in your file is more accurate than the data already in your OpenField Garden. 

Insert Data 

This option is best for adding new people to your OpenField Garden and/or matching to existing records. A knock canvass has different mapping requirements than a Phone Bank. 

• For Canvassing, you will need a First and Last Name and one of the following address field combos: 
  • Full Address
  • State + City + Address 1
  • State + City + Street Name + Street Number
  • State + City + Street Part + Street Number
• For Phone Banking, you will need a First and Last Name and one of the following phone fields:
  • Phone 1
  • Phone 2
  • Phone 3
  • Phone 4

✏️ Please Note: If you have a file to upload that includes contacts with an assortment of phone and address data, we recommend splitting those folks into three separate lists for import: one with the folks who only have phone data, one with those who only have address data, and one with the contacts who have both.

✏️ Please Note: You cannot insert a DWID or VAN ID if you choose the Insert Data option; please use either of the other options explained above. 

After selecting the appropriate Import Type, click Upload a new list. 

Uploading Your New List

In the Upload Your New List screen, you will provide a name and description for your imported List. These Lists will be available in Create a Search.

✏️ Please Note: Using an existing List name doesn't mean you are appending to a List, it will instead create a new List with the same name.

This will also be where you map the required fields based on the selected Import Type. 

 

✏️ Please Note: If your Import file contains a header row, remember to click the Ignore row 1 checkbox before Importing.

If you do not click this checkbox, you will receive an error message when running validation that says, “This error is in the first row, is that the header row and you forgot to ignore it? You can ignore the first row by checking the box at the top of the page.” 

✏️ Please Note: If an invalid value is found in the first 10 rows of your file, such as an improperly formatted phone number, email address, etc., the entire file may fail. Click the checkbox next to Validate first 10 example rows to proactively check your file for rows/values that might fail the validation check.  

✏️ Please Note: If you chose the incorrect Import Type, you can adjust it on the Upload Your New List screen. Click the dropdown box and re-select the correct Import Type.

Mapping Your Columns

To process your data, you must map all required fields based on your selected Import Type. The required fields will appear in red above your file's columns, helping you track which fields still need to be mapped. They will turn green as they are mapped. 

To map a column, click the drop-down above it in the preview of your list and map the corresponding OpenField field name. You can also leave the drop-down set to skip for any columns you don’t want to Import.

Repeat this process until all columns are mapped. Then, click Import Your List to run the Importer. 

Your file is now importing! When it finishes, you’ll see a fully loaded green bar and a “Success!” message

✏️ Please Note: Your list is not fully imported until the green bar of success is complete.

You will also see how many rows in your file were imported successfully. If any rows were not successfully imported, you can download them by clicking Download records that failed to import. See Error Handling below for more on how to handle errors.

Error Handling

Errors from Validation Check 

You will run into errors if your file contains values the Importer won’t accept. If you selected the checkbox to validate the first 10 rows of your file, the Importer will highlight the first row containing an error and provide a description of the error.  

In the image below, there were invalid phone numbers, values for sex that are not accepted, and improperly formatted email addresses. Return to your file, make the necessary adjustments, and then re-upload it.
✏️ Please Note: The import verification only runs on the first 10 rows of your file, so if there are errors in rows further down, you will not see them before clicking Import your list. Review our Import File Requirements at the top of this article for how to properly format your file.

Errors from Records that Failed to Import

If there were rows in your file that failed to import, you can discover why in the downloaded file when you click Download records that failed to import. A column named “error” will be added to the end of the file, containing a description of why the row failed to import. 

Fix the issue in the original file, or the downloaded error file, and then re-upload. 

✏️ Please Note: If a row contains multiple errors, only the first one recognized by the system will appear in the error column. Be sure to check the entire row for additional errors before re-uploading. 

Canceling an Import

If you need to cancel an in-progress Import, click Cancel next to the Import. 

You’ll be prompted to confirm the cancellation. Click Yes to confirm, and the Import will be stopped. 

✏️ Please Note: You cannot recover an Import once it has been canceled. You will need to begin a new Import.

 

Have more questions? Email us at [e-mail]. 

If you have feature requests or suggestions for how to improve OpenField, stop by our Product Suggestion & Feature Request page!