📌 Note: Memberships and vote history are available as add-ons or in our Political bundle. For more information on adding new features please see the add-ons page in your nation.

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

When you upload data, it must be saved as a comma separate file (.CSV). There are five different ways to import a .CSV file. All fields available for import are listed below. Every import must include a unique identifier. An asterisk indicates a unique ID field.

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.

We strongly recommend not using fields as proxy for other information. Extra data points can be added as tags. In some cases, it may make sense to create custom fields. Please contact your community strategist or help@nationbuilder.com to discuss if this option is right for you.

Table of Contents

Most Frequently Used

This category includes the fields most frequently used in that importer. The following fields are included in this category in the people import found at People > Import > One time import.

  • Address address1: Home address, first line.
  • Address address2: Home address, second line.
  • Address address3: Home address, third line.
  • Address city: Home city.
  • Address state: Home state.
  • Address zip: Home zip.
  • 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 leftmost email column mapped in a CSV for a first time import will be mapped as the primary email address. (When an import is overwritten, the rightmost email column mapped in that CSV becomes the primary email address.) Bad email addresses will be overwritten when importing additional emails. If all four emails are occupied by valid email addresses, additional imported addresses will be ignored.
  • employer: Text field.
  • 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.
  • 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.
  • 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.
  • phone_number: Numeric field.
  • tag_list: List of tags separated by commas. Can map more than one field to tag list. See overwrite non-blank fields FAQ for additional information.

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. 

  • 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 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_contact_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.
  • 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* : Text field.
  • rnc_regid* : Text field.
  • salesforce_id* : Text field.
  • 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.
  • ward: Political district only available in a voter file import.
  • website: Must be a valid URL. One address per record.
  • 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. 

Existing addresses will be overwritten if the overwrite box is checked and one of the following fields is mapped: 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

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: Last 4 digits of a Zip+4 code. Only to be used in conjunction with zip5 field.
  • zip5: First 5 digits of a Zip+4 code. Only to be used in conjunction with zip4 field.

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. 

In a donation import, the recruiter category is listed twice. While this is confusing, please be aware that the categories are distinct. The first recruiter category is for the person who introduced your nation. The second recruiter category is for the donation's fundraiser. Recruiters and fundraisers must have profiles in your nation before the import begins.

During a donation import, if you map to only one set of recruiter fields, the person will be listed as both recruiter and fundraiser. This is true regardless of which category you map. If you map to both categories, you can import a recruiter and a fundraiser for each donation. If a donation is imported without a fundraiser, the donor will be listed as the fundraiser.

  • 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: Last 4 digits of a Zip+4 code. Only to be used in conjunction with zip5 field.
  • zip5: First 5 digits of a Zip+4 code. Only to be used in conjunction with zip4 field.

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

Donation

This category is only available when doing a donation import. A donation import is used to import records of individual amounts donated at can be started from Finances > Donations > Import. If you map the tag_list field in a donation import, the donor's tags will be overwritten by the tags imported. This only happens during a donation import. During all other imports, the tag_list appends tags to a person's profile. Donations made by organizations can also be imported. Use the signup_type field to indicate that a donor is an organization. 

If you are trying to import a list of donors without individual donation records, use the one-time import found at People > Import > One-time import.

  • actblue_order_number: A unique ID for a donation created by ActBlue. Only map to this field if you are importing from ActBlue. Do not use if you are importing recurring donations.
  • amount* : Required field. Amount of donation in dollars and cents. Use a decimal point to separate dollars and cents. Do not include currency symbol. Can also import other currency.
  • amount_in_cents: Amount of donation in cents.
  • authorization: Authorization code from the credit card processor (unique identifier per transaction)
  • canceled_at: Date donation was canceled. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes). The importer will attempt to parse dates in other formats, but we cannot guarantee accuracy.
  • check_number: Numeric field.
  • created_at: Date donation record created in NationBuilder. We strongly recommend allowing the importer to automatically define this field as a record of when the import was created. If a donation record only has one date, we recommend mapping that date to the succeeded_at field.
  • custom fields: Custom donation fields will be listed in the donation category in alphabetical order by field name.
  • election_cycle: Election cycle when the donation will be applied. List of cycles will vary by nation and are created in Settings > Political > Election.
  • employer: Text field.
  • failed_at: Date donation failed. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes). The importer will attempt to parse dates in other formats, but we cannot guarantee accuracy.
  • fec_type_id: A numeral from 1-9 indicating the Federal Election Commission transaction type.
  • fec_type_name: The Federal Election Commission transaction type name.
  • fec_type_ngp_code: A letter indicating the Federal Election Commission transaction type.
  • first_name: Donor’s first name.
  • id: The NationBuilder ID for the donation itself. Map to this field to edit existing donations. If a donation does not exist in your database, this field must be left blank.
  • ip_address: The IP address of the donor at the time a donation is received.
  • is_private: Y/N Mark yes if the donor wants to remain anonymous and not have her contribution displayed on your website. Standard templates only show the name of a person who donated, not the exact amount of the donation.
  • last_name: Donor’s last name.
  • membership_id: The ID of the membership (which already exists in the nation) that the donation is applied to. Please email help@nationbuilder.com for help importing paid memberships.
  • ngp_id: The NGP ID of the donation being imported. Map to the ngp_contact_id field for the donor's NGP ID.
  • note: Background note for the donation - will be attached to the donation record, not to the donor's profile.
  • occupation: Text field.
  • page_slug: The page slug for a page within your nation's website where the donation was made. Must be a slug that exists in your nation. Can be used to attribute offline donations to an online progress bar.
  • succeeded_at: Date donation succeeded. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes). The importer will attempt to parse dates in other formats, but we cannot guarantee accuracy. If your import only has one date per transaction, we recommend mapping to this field.
  • tracking_code_slug: Tracking code to aggregate donations. These do not have to exist in your nation, prior to completing a donation import.

Ballots

These fields are only available in a ballot import. Voters must exist in the nation before ballots can be imported.

  • 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. Required in a ballot import.

Billing Address

You can only import a billing address during a donation import. A donation import is used to import records of individual amounts donated at can be started from Finances > Donations > Import.

One of these fields must be included in the import for the billing 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

Election

These fields are only available in a ballot import. Voters must exist in the nation before ballots can be imported. These fields define the election within which a ballot was cast. 

  • country_code: 2 letter code from ISO 3166. Required in a ballot import.
  • election_at: Date of the election in MM/DD/YYYY format. Required in a ballot import.
  • state: 2 letter code based ISO 3166-2. If the election is within the United States, this field is required.

Election periods

Both fields are available in donation imports. The name field is also available in ballot imports

These fields allow political campaigns to attribute donations to a particular election period. Proper attribution requires mapping both the election_cycle and one of the below fields. A donation import is used to import records of individual amounts donated at can be started from Finances > Donations > Import.

During a ballot import, the election period name defines what type of election occurred. 

Payment type

These fields are only available in a donation import to indicate how payment was received. A donation import is used to import records of individual amounts donated and can be started from Finances > Donations > Import.

Membership

Go to Settings > Defaults > Membership types > Import memberships to import memberships.

Paid memberships must be imported as two separate files: membership information and transaction information. 

Please note that memberships are only available to those on the Team plan or above. If you would like memberships activated in your nation, please contact help@nationbuilder.com.

  • expires_on: Date - must be in the form MM/DD/YYYY. If year is imported as two digits, the importer will assume it is 19YY.
  • id: Numerical value defined by NationBuilder for the individual membership.
  • name: Membership type name.
  • started_at: Date membership began - must be in the form of MM/DD/YYYY. If year is imported as two digits, the importer will assume it is 19YY.
  • status: Active, canceled, expired, grace period
  • status_reason: Short reason for the current status of membership.

Voter history

Voting features must be enabled at Settings > Defaults to access these fields. We recommend importing these fields when importing voters at People > Import > Voter file.

These fields can also be imported as part of a ballot import

  • is_absentee_voter: Y/N
  • is_active_voter: Y/N
  • is_early_voter: Y/N
  • is_permanent_absentee_voter: Y/N
  • voter_updated_at: Field only available in a ballot import. Indicates the 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).

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

Related HOWTOs

Fields available for import (old)
How to import

Did this answer your question?