How to import people into your nation

Seamlessly importing custom data into NationBuilder doesn't have to be hard. We've put together a list of our import fields and helpful tips, and you'll also want to check out these additional tutorials if they apply:

We recommend not using fields as proxies for other data - doing so makes it difficult to manage your nation and for others to query data relevant for their workflow. Tags are a good place to store extra data points, and you can add multiple tags separated by commas. If you have questions, drop us a line at help@nationbuilder.com.

Note: CSV imports are limited to 50mb per file - if your list is larger than that, you will need to divide it into multiple files.

Standard import fields

Items in italics are unique identifiers for NationBuilder. Unique identfiers can only be assigned to one signup record. An email address is a unique identifier and doesn't require a first or last name to be defined with the import. The other unique identifiers must have a first name and last name mapped during the import in order for the person to be imported into the nation.

Field Name Constrictions
email must contain valid email address (can be repeated up to four times per profile)
email_opt_in Y/N
name the full name of someone, leave blank if you provide first/last/middle name separately.
legal_name e.g. William instead of Bill
sex Must be M/F/O
party 1 character Party abbreviation - full list of political parties
marital_status C/D/M/P/S/W -(civil union, divorced, married, domestic partner, single, widowed)
is_deceased Y/N
dob Birthdate - must be in the form MM/DD/YYYY
phone_number include the area code
work_phone_number include the area code
mobile_number include the area code
mobile_opt_in Willing to receive text messages from nation - Y/N
is_mobile_bad Indicates mobile number is bad and will not accept text messages - Y/N
federal_donotcall On US Federal Do Not Call list - Y/N
do_not_call Does not want to be called by nation - Y/N
do_not_contact Does not want to be contacted by nation - Y/N
fax_number include the area code 
website Must be valid URL
language Primary spoken language - Two character abbreviation
created_at Date joined or imported to nation - must be in the form MM/DD/YYYY
support_level 1 =very strong support to 5 = very strong oppose
inferred_support_level 1=very strong inferred support to 5=very weak inferred support
priority_level value of 1 through 5, with 1 being low priorty and 5 being high priority
background Background field which shows at top of the person's profile
demo Demographic information
tag_list Tags separated by commas which will be added to person's profile. See Overwrite non-blank fields FAQ entry for more information.
assistant_name_or_email Must be valid person in your nation
recruiter_id NationBuilder ID of the recruiter for this person
recruiter_name_or_email Recruiter's name or email address - Must be valid person in your nation
parent_id NationBuilder ID for point person for this profile
point_person_name_or_email Point person's name or email address - Must be valid person in your nation
id (Under 'Signup') NationBuilder ID for this person - Must be blank for imports. Must be numerical for updates
signup_type 0 = person, 1 = organization
twitter_id  At most one Twitter account per record. At most one record per Twitter account.
address_country_code  2 letter code from ISO 3166
work_country_code   2 letter code from ISO 3166
mailing_country_code   2 letter code from ISO 3166
is_volunteer Y/N
DONOR ADDON (*indicates has bank account with the NYC option checked)
is_fundraiser Y/N
is_ignore_donation_limits Y/N
MEMBERS ADDON Membership information can only be imported from Settings > Defaults > Membership types > Import memberships

Related how to guides

Do you like this page?

Showing 22 reactions

Wrap code snippets in <code></code> tags.

  • commented 2015-01-09 15:46:26 -0800 · Flag
    Can I import organizations this way?
  • commented 2014-09-04 11:52:54 -0700 · Flag
    If a file is mapped to import people as prospects, it will not downgrade the support status of existing people in your nation. Only new people added to your nation will be imported as prospects.
  • commented 2014-07-29 12:09:48 -0700 · Flag
    The website field can only accept one URL. The only fields that can be mapped more than once are the tag list (unlimited comma separated tags) and email (up to four email addresses per person).
  • commented 2014-07-22 11:58:17 -0700 · Flag
    Dan, the best way to import elections people voted in is by importing voter history. You’ll need to import voters first: http://nationbuilder.com/how_do_i_import_my_custom_voter_file then import voter history: http://nationbuilder.com/how_do_i_import_custom_voter_history

    You can definitely segment people based on tags and contact history by using filters. More info here: http://nationbuilder.com/how_to_filter
  • commented 2014-07-22 11:56:28 -0700 · Flag
    The error message Andrew Olsen experienced is because he did not map a unique identifier for import. Only one unique identifier is needed – the error message was in red to indicate that the import could not begin without it. More info here: http://nationbuilder.com/what_is_a_unique_identifier
  • commented 2014-07-05 17:55:23 -0700 · Flag
    Are tags the best way to import the elections voters voted in ?

    example: ‘2012 primary’, ‘2012 main’

    Can I curt turfs based on tags and contact history ?
    for example:
    ‘2012 main’ and NOT previously_contacted.
  • commented 2014-06-22 05:59:46 -0700 · Flag
    A lot of people I want to import have two or more websites. Can I just make multiple “website” fields for each person?
  • commented 2014-05-19 08:02:51 -0700 · Flag
    Andrew, this is probably a support question, and perhaps it’s already been answered. My guess is that you have some extraneous rows that have just a bit of data. Each record must have at least one of the fields you listed. So if you had a row with just, let’s say, a precinct number, it would cause the import to fail. If you sort your csv file by last name, you ought to be able to find the bad record(s)
  • commented 2014-05-16 15:49:19 -0700 · Flag
    I am trying to import simple voter data for the purpose of producing walk lists. It keeps generating this message:
    Missing required match field. Please map one of: id, nbec_guid, pf_strat_id, ngp_id, van_id, rnc_id, rnc_regid, civicrm_id, external_id, county_file_id, state_file_id, dw_id, email, twitter_login, twitter_id, facebook_uid, meetup_id, salesforce_id, or first_name, last_name, born_at and either phone_number, mobile_number, or work_phone_number

    In red, no less. Should I just create all these fields with unique random values to work around? Would be nice not to have to.
  • commented 2014-05-02 10:41:59 -0700 · Flag
    We do have custom fields available. Please talk to your organizer about whether it is the best path for your nation – tags may be a better option for the type of information you’re looking to store. More information on implementing custom people fields is available at: http://nationbuilder.com/how_to_create_custom_people_fields
  • commented 2014-05-02 10:14:40 -0700 · Flag
    the same question, i need add more fields for people, the relevant information in my country is some different
  • commented 2014-03-20 01:35:59 -0700 · Flag
    Can we add custom field for People? i mean i want to store some extra information and then want to search people on that extra information. Is this functionality available?
  • commented 2014-03-03 11:19:47 -0800 · Flag
    Monika, we plan to make this possible down the road, but it is not possible to do so currently. I’ll send you some follow-up info your way in a few minutes.

    Juan (your organizer)
  • commented 2014-03-02 20:56:12 -0800 · Flag
    Some of the data I want to import already has linked supporters in households together by stating they’re spouses/parents/siblings/etc. Is it possible to map this info when I upload the data? It is very slow-going to do this manually.
  • commented 2014-02-20 12:40:03 -0800 · Flag
    If you’re importing new people into your database, you can upload notes into the background field. This is not intended as a way to import multiple notes on a single person, as there is only one background field and if you overwrite nonblank fields, your new background note will erase the previous information in that field.

    Be sure that the email address field is completely blank if you don’t have an email address for someone.

    Full description of unique identifiers is here:

    That page also explains how to create unique identifiers on import if a unique identifier doesn’t already exist.
  • commented 2014-02-11 20:36:55 -0800 · Flag
    I am trying to import a .csv file into our NB and not all the people have an email. Also I have a “Note” field which I’d like to import into Private Notes, but I don’t see that field being offered at import time. The import fails because “There appears to be an unusual amount of invalid emails on this list that could hurt your deliverability.” How can I import my list, with only some emails and also having Notes?
  • commented 2014-01-30 18:38:16 -0800 · Flag
    as you work on this one, it would be great to just make it an update feature. Sometimes we receive data that might be a couple years old with records that are no longer valid. trying to figure that out prior to importing is a hassle. Not a huge deal, but should be part of an update functionality
  • commented 2014-01-20 16:37:17 -0800 · Flag
    Naomi – our engineering team is looking into the import process. The functionality you describe is happening currently, but our intention is that if people already exist in your database as supporters that their status isn’t changed by being on an import list marked prospects. I will post again when I have an update from the team.
  • commented 2014-01-20 00:20:25 -0800 · Flag
    Adriel – I’ve asked for help with this before in ‘suggestion’ section but can’t find the post.

    I’m having the same problem as these guys, I’m importing data from different sources and people who are already supporters in my database are getting knocked back to prospects because they are on another list that I want to import as prospects (for example a old paper petition). It’s hard to even find who is affected unless you know the data well.

    My preference would be that people uploaded as prospects who are already marked as supporters on the database remain as supporters a the default. Tagging and batch update could then be used if you really needed to remark people as supporters.

    Why isn’t this the case, what is the logic here?
  • commented 2013-10-07 15:15:36 -0700 · Flag
    Good question, David – supporters are folks who’ve opted in, while prospects are folks you’re still reaching out to. On an import, you can bring in a support level of 1-5 to indicate support/non-support, but in an import new people without a support level can be brought in as either the supporter/non-supporter or prospect category. If you’re updating existing records, you’ll probably want to use supporter with or without a numerical support level. If you were importing new people who you have yet to contact in your organizing efforts, you’d want to use prospects.

    Additional info: http://nationbuilder.com/what_is_a_broadcaster_supporter_prospect
  • commented 2013-10-06 19:04:37 -0700 · Flag
    A Support Level category is a mandatory selection – either “Supporters/Non-Supporters” or “Prospects”, but this choice isn’t really explained, here or on the import page.
    Most of my imports involve updating existing records – it’s not clear which of these options is better for that situation.
  • commented 2013-10-06 10:06:42 -0700 · Flag
    why is it impossible to ask a friggin question? i thought this was going to be a great experience but i has me infuriated and completely aggro….pomg. wth is so hard about simply putting a visible link to ask a question????