How to import vote history

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 > More > Import > Ballots import. When importing directly into the control panel of your nation, the file must be UTF-8 standardized, comma separated file (CSV).

Please note: The vote history model used in NationBuilder was changed in July, 2015. 

As of July, 2016, all customers with voters enabled in their nation can import ballots through the control panel once voters exist in their nation. If you are one of the few customers using the deprecated importer / deprecated vote history model, we strongly recommend formatting your imports using the one record per ballot method described below. The current ballots importer processes data at a much faster rate than the deprecated importer, which means you will be able to run filters and target voters faster. Please contact help@nationbuilder.com to be upgraded to the current, faster ballots importer. 

If you are in the United States and request a voter file directly from NationBuilder, both the voters and ballots will be uploaded to your nation. 

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. 

 

Signup

Field Description
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

Field Description
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

Field Description
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

Field Description
name 1 of 10 pre-defined election period names.

 

Registered address

Field Description
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. 

Field Description
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). 

 

*Fields are required. 

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:

example ballot history layout

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 help@nationbuilder.com and provide the following information to help you expedite the import process:

  1. The district(s) to be imported.
  2. 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. 
  3. 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 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 deliminated, Excel, text document, or CD - you can send the file. The Services Team can usually transform data before we 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.


How to import voters

Unique identifers

Election periods

Political parties available for import

Vote method codes

If you’re unclear on how this feature works, please ask a question. If you would like to see changes to this feature, please submit a suggestion.