Table of Contents
Ballots are imported as a historical record of when elections occurred and how an individual voted in that election. A nation must have enabled voter features at Settings > Defaults > Basics and voters must already exist in the nation to import ballots.
Once voters exist in your nation, vote history can be imported in the People section at People > Import > Ballots. When importing directly into the control panel of your nation, the file must be UTF-8 standardized, comma separated file (CSV).
Only particular fields related to past elections can be imported during a vote history import because this information exists in a separate table from profile information and is connected using a unique identifier.
Fields available for import
The fields available are listed in categories. Three of these categories contain fields located in the voter's profile: signup, registered address, and voter. These fields are used primarily to connect the vote history with the voter.
The other three categories are aspects of the vote history, and are stored within the vote history table.
Each record imported represents one ballot cast by one person. Therefore, there are required fields to properly create a record of the ballot cast and there are required fields to attach that record to the voter's profile.
At a minimum, a ballot must include vote method, election country code, and election at (the date of the election). For United States elections, the election state must also be imported. Each record must also include a profile unique ID - either NationBuilder ID, Voter GUID, state file ID, or county file ID.
If the state file ID is imported, the registered state field must be imported. If county file ID is imported, both the registered state and registered county fields must be imported. These IDs become unique identifiers in combination with the associated registered address fields. Therefore, in order to attach the ballot to the existing voter, the registered state field must be imported as a two-letter abbreviation based on ISO 3166-2 standards. The registered county field must be imported exactly as it appears within a voter's profile.
Note that election state and registered state are different fields and often both fields must be imported.
📌 Note: Fields marked with an * below are required.
Signup
county_file_id: A unique profile ID that already exists on profiles in your nation. If you map to this field, you must also map registered state and registered county fields. How you format registered state and county is extremely important.
id: The NationBuilder ID for a voter, auto-generated within your nation when the profile was created.
state_file_id: A unique profile ID that already exists on profiles in your nation. If you map to this field, you must also map registered state field, using the official two-letter abbreviation for the state.
Ballots
cast_at: Date the ballot was cast.
party: When voters receive separate ballots based on political party preference, the full name of political party on the ballot received. Primarily used in the U.S.
vote_method* : One of the following vote methods: voted, early, or absentee.
Election
country_code* : Required 2 letter code from ISO 3166.
election_at* : Required date of the election in MM/DD/YYYY format.
state† : Required 2 letter code if the election is within the United States.
Election_Period
name: Full name of the election period, like "General" or "Primary". There are 10 pre-defined election period names.
Registered address
county‡ : Required if also importing county file ID. You must import the registered county exactly as it appears within a voter's profile.
state‡ : Required if importing county file ID or state file ID. You must import registered state as a two-letter abbreviation based on ISO 3166-2 standards.
Voter
We do not recommend importing these fields in a ballot import. Most fields should be imported using the voter import.
guid: Voter GUID, a unique ID for a voter. Part of the NationBuilder Voter File.
is_absentee_voter: Y/N
is_active_voter: Y/N
is_early_voter: Y/N
is_permanent_absentee_voter: Y/N
voter_updated_at: Date the voter was updated. We strongly recommend allowing the importer to automatically define this field as a record of when the import was created. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes).
The ballot importer expects all dates to be in the MM/DD/YYYY format. Please transform the data to this format prior to importing.
†Election state is required for elections occurring in the United States. It is not required if any other country code is used.
‡Registered state field is required if importing state file ID or county file ID. Registered county field is required if importing county file ID.
Sample file
Each record being imported represents a person's vote history for a single election. Therefore, the same person can be connected to multiple records. Here is an example of how a correctly formatted CSV would display in Excel:
You can also download this sample ballots CSV.
In the past, a record represented a person's entire vote history. It is important that files be uploaded using the current file format rather than the deprecated version.
Support for ballots imports
All customers with voters enabled in their nation can import ballots through the control panel once voters exist in their nation. In order to use the ballots importer, you must format your imports using the one record per ballot method. If you have trouble importing the data, please send the file to [email protected]and provide the following information to help you expedite the import process:
The district(s) to be imported.
Information on when the election(s) occurred. This can either be a combination of election period and year of election or the exact date of the election.
The file format being provided. The preferred file format is UTF-8 standardized, comma separated file (CSV).
You may have more vote history than you are interested in placing in your nation - either because it includes voters outside of your district or because you do not need the breadth of vote history available.
If you request additional help from the NationBuilder Professional Services Team, pricing for data imports may be subject to an initial scoping and is available upon request.
When making these requests, the preferred file format for vote history imports is UTF-8 standardized, comma separated file (CSV).
If the dates in your file are not in MM/DD/YYYY format, e.g. DD/MM/YY, please include explicit instructions on the date format when submitting the file. The Services Team can standardize dates when clear information on the field formatting is received.
If your ballots exist in another format - e.g. tab delimited, Excel, text document, or CD - you can send the file to us. The Professional Services Team can usually transform data before they begin the import. Please note: This functionality does not exist when importing vote history directly in the control panel. All imports done directly within your control panel must be UTF-8 standardized, CSVs.
Completing a NationBuilder ballots import
When you request a voter file uploaded to your nation, the voters will be imported for you, and a link to the ballots upload will be provided. (Ballots are optional—if you don't need vote history for your use, you can skip this step.)
Voters will need to finish uploading before you start the ballots import, so ballot data can be linked to the correct voters without error. To check on the voter file import progress, go to People > Imports > Voter file.
Once the status is "Finished," you can import ballots.
📌 Note: Don’t be alarmed if there are some errors. A few records will be rejected in most imports, but the intended data will be in your nation once the status is “Finished."
Ballots are imported at the ballots link provided in your email. Under "Use settings from a previous import," select the file with your state abbreviation and "ballots.csv."
Click the Start import button and you're good to go.
Related HOWTOs