Fields available for import

When you upload data, it must be saved as a comma separate file (.CSV). All fields available for import are listed below. There are five different ways to import a .CSV file. 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.


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 > More > Import > One time import

Field name Description
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 last email mapped will be identified as the profile's primary email address. Bad email addresses will be overwritten when importing addition emails. If all four emails are occupied by valid email addresses, additional imported addresses will be ignored.
employer  
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  
phone_number  
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 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 Date joined or imported to nation - 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
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. Four digits are required for year accuracy. If year is imported as two digits, it will be imported as 19YY.
donations_to_raise_amount  
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 last email mapped will be identified as the profile's primary email address. Bad email addresses will be overwritten when importing addition emails. If all four emails are occupied by valid email addresses, additional imported addresses will be ignored.
email_opt_in Y/N - opted into receiving email from your nation
employer  
ethnicity  An open-ended text field - any ethnicity can be imported using this field
external_id* Unique identifier
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 enable donor features to display within your nation
is_ignore_donation_limits Y/N - you must enable donor features to use
is_mobile_bad Y/N - indicates mobile number is bad and will not accept text messages
is_volunteer Y/N - you must enable volunteer features 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* Unique identifier, part of the NationBuilder Voter File. Listed as Voter GUID in the ballot importer.
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. During a donation import, mapping to this field will overwrite existing tags.
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* Unique identifier
village_district Political district only available in a voter file import.
ward Political district only available in a voter file import.
website Must be a valid URL. One address per record.
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. 

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.

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  

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  

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 > More > Import > One-time import.

Field name Description
actblue_order_number An ID for the donation created by ActBlue. Only map to this field if you are importing from ActBlue.
amount Amount of donation in dollars and cents
amount_in_cents Amount of donation in cents
authorization Authorization code from the credit card processor
canceled_at Date donation was canceled. Format should be "MM/DD/YYYY" or "hh:mm:ss MM/DD/YYYY" (without quotes). The importer will attempt to parse dates in other formats, but we cannot guarantee accuracy. Four digits are required for year accuracy. If year is imported as two digits, it will be imported as 19YY.
check_number  
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  
failed_at Date donation failed. Format should be "MM/DD/YYYY" or "hh:mm:ss MM/DD/YYYY" (without quotes). Four digits are required for year accuracy. If year is imported as two digits, it will be imported as 19YY.
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  
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  
membership_id The ID of the membership (which already exists in the nation) that the donation is applied to. Please contact your community strategist 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  
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 thermometer. 
succeeded_at Date donation succeeded. Format should be "MM/DD/YYYY" or "hh:mm:ss MM/DD/YYYY" (without quotes). Four digits are required for year accuracy. If year is imported as two digits, it will be imported as 19YY.
tracking_code_slug  Tracking code to aggregate donations. Must already exist in your nation and can be created at Finances > Tracking codes

Ballots

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

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

Field name Description
address1  
address2  
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. 

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

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. 

Field name Description
election_period_name 1 of 8 election period names
ngp_code 1 of 8 letters indicating election period 

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.

Field name Description
id 1 of 10 valid payment IDs
name 1 of 10 valid payment names
ngp_code 1 of 9 valid payment ngp codes

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 Organization plan or above. If you would like memberships activated in your nation, please contact help@nationbuilder.com.

Field name Description
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 > More > Import > Voter file import.

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

Field name Description
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 feild as a record of when the import was created. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes).

What is a unique identifier?

Take a snapshot before importing

Preparing for your first import

How to start an import

When imports overwrite existing data

How to import organization profiles


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.

Not finding what you're looking for? Browse the People FAQs