How to import a voter file

You must enable voter features in your nation at Settings > Defaults > Basics. A voter file includes a list of people eligible to vote. Vote history is imported separately, after voters are added. Using a voter file import, it is possible to include many political fields not available in a one-time import, including voting districts. Start a voter file import from People > More > Imports > Voter file.


Before you import

Detailed instructions are available on preparing for an import. Important highlights:

  1. If you already have data in your nation, take a snapshot before starting an import. The snapshot must finish before you begin the import.
  2. If you are certain that the appropriate political districts exist in your voter file, turn auto-districting off before you begin importing.
  3. Make sure your file includes unique identifiers.
  4. Understand how importing affects existing data.
  5. Mapping fields ensures data isn't lost or placed incorrectly. 
  6. Some fields only accept data in a particular format - pay attention to any restrictions indicated.

Auto-districting

Auto-districting is the process of locating a profile's voting districts automatically. When auto-districting is turned on, voting districts will be automatically placed in a profile based on primary address. These districts will be updated when the primary address changes and when new district maps become available to NationBuilder.

If you are certain that the appropriate political districts exist in your voter file, turn auto-districting off before you begin importing a voter file.


Unique IDs

Every import must include unique identifiers. Please note that for state file ID to be considered a unique ID, it must be imported with registered state. Similarly, for county file ID to be considered a unique ID, it must be imported with registered county and registered state. Additional information is available on unique IDs and importing addresses.


U.S. voters

NationBuilder offers free access to the national voter file to U.S. organizations for political purposes. When making your request, check the "I would like to have the file imported into my nation" box to have the voters added directly to your nation.  


UK localization

Voting districts will display using local standards for nations based in the UK. A nation's location is determined by the address listed in Settings > Contact. While local district names will appear in the control panel, one database structure exists for all nations. Therefore, you must use the NationBuilder field name when importing voting districts.

If you are importing voting districts and are confident in the accuracy of your data, remember to turn off auto-districting before you begin the import. 

British district NationBuilder field name
eu_parliamentary_constituency supranational_district
westminster_parliamentary_constituency federal_district
labour_region labour_region
scottish_welsh_london_constituency state_lower_district
council county_district
wards precinct_name

Canadian localization

Voting districts will display using local standards for nations based in Canada. A nation's location is determined by the address listed in Settings > Contact. While local district names will appear in the control panel, one database structure exists for all nations. Therefore, you must use the NationBuilder field name when importing voting districts. 

If you are importing voting districts and are confident in the accuracy of your data, remember to turn off auto-districting before you begin the import. 

Canadian district NationBuilder field name
Provincial Electoral Divisions state_upper_district
Provincial Constituencies state_upper_district
Provincial Polls state_lower_district
Administrative Districty county_district
Municipal District city_district
Municipal Poll city_sub_district

Fields available in voter file import

Fields that can be imported are categorized. You can search for field names when mapping your fields, but not for the category names. Some fields exist within multiple categories, so take care to map the correct field to your data. If a field can only be imported using a particular importer, that is noted.


Most frequently used

This category includes the fields most frequently used when importing voter files. Other types of imports will list different fields in this category.

Field name Description
NBec precinct nbec_code A precinct is defined by the combination of precinct_code and precinct_name. If importing precinct information, please import both the code and the name.
Precinct name A precinct is defined by the combination of precinct_code and precinct_name. If importing precinct information, please import both the code and the name.
Registered address1  Part of the address where person is registered to vote.
Registered address city  Part of the address where person is registered to vote.
Registered address state  Part of the address where person is registered to vote. Must be imported if importing state file ID or county file ID.
Registered address zip  Part of the address where person is registered to vote.
first_name  
last_name  
middle_name  
phone_number  
state_file_id  Unique identifier if mapped with the registered state field. May be zero filled to number of digits defined by state.

Signup

Within the code, a person or organization in your nation is referred to as a "signup." People in your database do not have to sign up on your website to be considered a signup. It is simply a way to distinguish a person from a webpage or other aspect of your nation. Most other field categories are actually sub-groupings of signup fields. The distinction between people and organizations is made using the signup type field. 

Field name Description
Donations to raise amount  
assistant_name_or_email Must be a person who already exists in your nation
availability  
background The note field that appears at the top of a person's profile. The only type of note that can be imported - only one background per person.
church  
city_district Political district only available in a voter file import.

city_sub_district

Political district only available in a voter file import.
CiviCRM ID* Unique identifier
county_district Political district only available in a voter file import.
county_file_id* Unique identifier if mapped with the registered state and registered county fields. May be non-zero filled state ID in some states.
created_at We strongly recommend not importing to this field. Please allow the importer to define the date a record is created within your nation based on the date of the import. If imported, date must be in the form MM/DD/YYYY.
custom fields Custom people fields will be listed in the signup category, in alphabetical order by field name.
demo One letter demographic code
datatrust_id* Unique identifier
do_not_call Y/N - does not want to be called by nation
do_not_contact Y/N - does not want to be contacted by nation
dob Date of birth / birthdate - must be in the form MM/DD/YYYY. If you are importing organizations, you can map the founding date of an organization to this field.
donations_to_raise_amount_in_cents  
dw_id* Catalist ID, a unique identifier.
email* Must contain a valid email address. A unique ID. Each profile can have up to four email addresses, so the field can be mapped up to four times. The first email mapped will be identified as the profile's primary email address.
email_opt_in Y/N - opted into receiving email from your nation
employer  
ethnicity  
external_id* Unique identifier
facebook_uid* Unique identifier, numerical ID for a Facebook user
facebook_username* Unique identifier, publicly visible Facebook username
fax_number  
federal_donotcall Y/N - registered on the U.S. federal do not call list
fire_district Political district only available in a voter file import.
first_name When importing people, either map to the first name and last name fields or import "First Name Last Name" into the name field. When importing organizations, map to the organization name to the last name field. 
id* NationBuilder ID, a unique identifier auto-generated within your nation. 
inferred_party Only available in a voter file import. Single letter abbreviation for political party.
inferred_support_level A number from 1-5. 1=very strong inferred support and 5=very strong inferred opposition
is_deceased Y/N
is_fundraiser Y/N - you must have donor features enabled to display within your nation.
is_ignore_donation_limits Y/N - you must have donor features enabled in your nation to use.
is_mobile_bad Y/N - indicates mobile number is bad and will not accept text messages.
is_volunteer Y/N - you must have volunteer features enabled to display within your nation.
judicial_district Political district only available in a voter file import.
language Primary spoken language - abbreviation code required
last_name When importing organizations, map the organization name to this field. When importing people, either map to the first name and last name fields or import "First Name Last Name" into the name field.
legal_name  
marital status Single letter code for marital status
meetup_id* Unique identifier
middle_name When importing people, map this field with the first name and last name fields. If importing middle names, do not use the name field. 
mobile_number  
mobile_opt_in

Y/N - willing to receive text messages from nation.

name When importing people, first and last name in one field. The importer will separate them into the first name and last name fields. Because of this functionality, do not map all three fields: only map the name field or map the first name and last name fields. When importing organizations, do not use this field. An organization's name should be mapped to the last name field.
nbec_guid* NationBuilder Voter ID, unique identifier defined in the NationBuilder Voter File.
ngp_id* Unique identifier. To distinguish it from a donation ID, this field is named ngp_contact_id on the donation import. In a donation import, ngp_id refers to the donation, rather than to the donor.
occupation  
parent_id The NationBuilder ID of the profile's point person.
party Single letter abbreviation for political party
party_member Y/N
pf_strat_id* Unique identifier
phone_number  
point_person_name_or_email  
prefix  
previous_party Only available on voter file import. Single letter abbreviation for political party.
priority_level Priority level is a number from 1-5. 1=lowest priority and 5=highest priority
recruiter_name_or_email Only available on voter file import. We recommend using the fields in the recruiter category, rather than this field.
registered_at The date this person registered to become a voter - must be in the form MM/DD/YYYY.
religion  
rnc_id* Unique identifier
rnc_regid* Unique identifier
salesforce_id* Unique identifier
school_district Political district only available in a voter file import.
school_sub_district Political district only available in a voter file import.
sex Must be a single letter: M, F, or O (male, female, or other)
signup_type Indicates whether the record represents a person or an organization. Must be a single digit: 0 or 1 (0=person, 1=organization). If not specified, imports are assumed to represent people. 
state_file_id* Unique identifier if mapped with the registered state field. May be zero filled to number of digits defined by state. 
suffix  
support_level A number from 1-5. 1=very strong support and 5=very strong opposition. Support level defines support status, indicating whether a person is a supporter or non-supporter. 
support_probability_score Only available in a voter file import.
tag_list You can map multiple fields to tag list and the tags will be added to the tag list for the record.
township/td> Political district only available in a voter file import.
turnout_probability_score Only available in a voter file import.
twitter_id* Unique identifier, numerical ID from Twitter
twitter_login* Unique identifier, Twitter username - do not include the @ sign
van_id* Unique identifier
village_district Political district only available in a voter file import.
ward Political district only available in a voter file import.
work_phone_number  

Address

The fields in this category will create a home address for the profile. Do not use these fields for an organization. An organization's address should be mapped to work address.

One of these fields must be included in the import for the address to be created: address1, city, or country code.

Field name Description
address1  
address2  
address3  
city  
country  
country code 2 letter code from ISO 3166
county  
FIPS  
state  
zip  

Mailing address

If you use the address1, address2, and address3 fields, the information will be parsed into the street name, street number, street prefix, street suffix, street type, and unit number fields. Therefore, either map address1, address2, and address3 fields or map street name, street number, street prefix, street suffix, street type, and unit number. Similarly, either map to the zip field for a mailing address postal code or map to zip4 and zip5. 

One of these fields must be included in the import for the mailing address to be created: address1, street name, city, zip5, or country code.

Field name Description
address1  
address2  
address3  
carrier route  
city  
country  
country code 2 letter code from ISO 3166
county  
delivery point  
FIPS  
lot  
sort sequence  
state  
street name  
street number  
street prefix  
street suffix  
street type  
unit number  
zip  
zip4  
zip5  

Media Market

Field name Description
media market name  

Precinct

A precinct is the smallest unit of organization for a campaign. Each precinct is a defined as the unique combination of precinct_code and precinct_name. Precincts are never included in auto-districting.

Field name Description
precinct_code  
precinct_name  

Recruiter

The person who introduced your nation. A profile for the recruiter must already exist in your nation. All fields within this category refer to the recruiter. To ensure the correct person is credited with recruiting the person, try to use the recruiter's email address or NationBuilder ID. 

Field name Description
email A valid email address already attached to the recruiter's profile.
first_name The recruiter's first name, as it exists in your nation. Should also map recruiter's last name.
id The recruiter's NationBuilder ID.
last_name The recruiter's last name, as it exists in your nation. Should also map recruiter's first name.

Registered address

The address where the person is registered to vote. You have the same options for this address as you do for mailing address - either map address1, address2, and address3 or map street name, street number, street prefix, street suffix, street type, and unit number. Similarly, either map to the zip field for a mailing address postal code or map to zip4 and zip5. 

One of these fields must be included in the import for the registered address to be created: address1, street name, city, zip5, or country code.

If you only map registered state or registered state and registered county fields, the registered address will not be updated. Those fields will be used with state file ID or county file ID to define a unique identifier in the import / match in your people database.

Field name Description
address1  
address2  
address3  
carrier_route  
city  
country  
country_code 2 letter code from ISO 3166
county Required field if mapping county file ID. Extremely important to maintain consistency in how the county is identified across imports. 
delivery_point  
fips  
lot  
sort_sequence  
state Required field if mapping state file ID or county file ID. Should be the 2 letter code based on ISO 3166-2 standards.
street_name  
street_number  
street_prefix  
street_suffix  
street_type  
unit_number  
zip  
zip4  
zip5  

Signup profile

Field name Description
website Must be a valid URL. One address per record.

Voter

Field name Description
is_absentee_voter Y/N
is_active_voter Y/N
is_early_voter Y/N
is_permanent_absentee_voter Y/N

Work address

When importing organizations, always map physical location to these fields. 

One of these fields must be included in the import for the work address to be created: address1, street name, city, zip5, or country code.

Field name Description
address1  
address2  
address3  
city  
country  
country_code  2 letter code from ISO 3166
county  
FIPS  
state  
zip  

Prepare for an import

Take a snapshot before importing

Auto-districting

Unique identifiers

How importing affects existing data

How to map fields

Primary address and importing addresses

How to migrate data from NGP VAN to NationBuilder

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.