📌 Note: Features are available in our Political bundle. For more information on adding new features please see the add-ons page in your nation.

Table of Contents

Before you import

First, 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. Once you've enabled voter features, start a voter file import from People > Import > Voter file.

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.

📌 Note: 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 under your profile icon > Contacts and billing. 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 under your profile icon > Contacts and billing. 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 District: 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.

  • 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: Text field.
  • last_name: Text field.
  • 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.
  • phone_number: Numeric field.
  • 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 another 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. 

📌 Note: Fields marked with an * below are unique identifiers.

  • Donations to raise amount: Goal for person to fundraise.
  • assistant_name_or_email: Must be a person who already exists in your nation.
  • availability: Times available to volunteer.
  • 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: Church maps to a field in your NationBuilder control panel called Place of Worship. Please note that this field doesn't exist in some countries where collection of this type of data is not permitted under law.
  • 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.
  • datatrust_id* : Unique identifier.
  • demo: One letter demographic code.
  • 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: Numeric field.
  • 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: Place of employment.
  • ethnicity: Open text field.
  • external_id* : Unique identifier.
  • facebook_uid* : Unique identifier, numerical ID for a Facebook user.
  • facebook_username* : Unique identifier, publicly visible Facebook username.
  • fax_number: Numeric Field.
  • 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 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: Text field.
  • marital_status: Single letter code for marital status.
  • meetup_id* : Text field.
  • 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: Numeric field.
  • 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: Text field.
  • 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: Numeric field.
  • point_person_name_or_email: Text field.
  • prefix: Text field.
  • 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: Text field.
  • rnc_id* : Text field.
  • rnc_regid* : Text field.
  • salesforce_id* : Text field.
  • 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: Text field.
  • 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: 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* : Text field.
  • village_district: Political district only available in a voter file import.
  • ward: Political district only available in a voter file import.
  • work_phone_number: Numeric field.

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.

  • address1: Home address, first line (street number, street name, street prefix/suffice, street type).
  • address2: Home address, second line (unit number).
  • 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.

  • address1: Home address, first line (street number, street name, street prefix/suffice, street type).
  • address2: Home address, second line (unit number).
  • 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

  • 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.

  • 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. 

  • 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.

  • address1: Home address, first line (street number, street name, street prefix/suffice, street type).
  • address2: Home address, second line (unit number).
  • 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

  • website: Must be a valid URL. One address per record.

Voter

  • 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.

  • address1: Home address, first line (street number, street name, street prefix/suffice, street type).
  • address2: Home address, second line (unit number).
  • address3
  • city
  • country
  • country_code: 2 letter code from ISO 3166
  • county
  • FIPS
  • state
  • zip

Related HOWTOs

Prepare for an import
Take a snapshot before importing
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

Did this answer your question?