Table of Contents

Before you import

We suggest that you take a snapshot of your nation before running imports. This allows your nation to be easily restored to its previous state if you change your mind or something goes wrong.

Importing data

To start, make sure your import file is formatted as UTF-8 standardized, comma separated files (CSV). Then, navigate to People > Import

Step 1: Upload your file

1. Click Choose File and select the file from your computer.

2. Click Upload CSV file

Step 2: Map fields

Mapping fields means telling your nation what type of data can be found in each field (column). You must map to fields available for import. Check out a complete list of fields available for import. If your field cannot be imported, you might be able to map your data as a tag or custom field.

Do the fields need to be in a certain order? 

Not necessarily, but typically people order them: First name, Last name, Unique ID, Phone number, Email address, etc. 

Does NB have an example CSV? 

We sure do. Here's a basic import file example

To start mapping, select the data field from the dropdown menu at the top of each column.

Keep in mind, different fields of the same name exist under different category headers which produce different results. 

For example, there are a variety of Address category choices (i.e. Mailing, Work, etc.), make sure that if you have an address with multiple lines, you are using Address 1, Address 2, Address 3 under the same heading. 

E.g. if I'm entering a Mailing Address with multiple lines, I need to use Address 1/2/3 under Mailing Address.

While mapping you may see some error text, don't fret. Every time fields are mapped, the system will validate the first row of data to confirm it looks correct. 

In the example above, I mapped fields, but missed a step. I haven't mapped a required unique ID field. I will be unable to import the file until this error is fixed. 

Also, make sure to check the box next to "don't import" to tell the system the first row contains header information and the second row of data can be validated. 

Step 3: Customize your import

The third step is defining settings for the import. Seven options appear on one-time imports. Fewer choices are included in other imports.

1. Decide whether to overwrite existing signup data. The unique ID imported with a record could connect it to an existing profile in your nation.

2. Support status- Profiles always have a support status, which is supporter, non-supporter, or prospect.

If the records being imported are people who have opted into communication, select Supporters/Non-supporters. Any new profile created with an email address, mobile number, Facebook username/ID, or Twitter login/ID will be labeled a supporter. Other profiles will be created as non-supporters.

If the records being imported are people who have not opted into communication, select Prospects. When prospects is selected, all profiles created will be labeled prospects, including records with email address, mobile number, Facebook username/ID, or Twitter login/ID.

In certain circumstances, information being imported may override the rules above. Please see how support status is determined for more information.

3. Activity stream- Decide whether to show that each profile was added in the activity stream in the Dashboard section and on the person's profile. Sometimes, this can be useful. Other times, it is just clutter.

4. Add tags to each person- Tags are like virtual sticky notes that you can attach to a person’s profile to highlight certain criteria or characteristics. It's always recommended to add a tag to any import that may be updating data so that you can filter for this group after the fact. 

If a tag or tags should be added to every record imported, include it in this text box. Tags can have spaces. Including a comma separates one tag from another tag. Tags included in this text box will be appended to the tag list for each person added/updated by the import.

5. Bypass webhooks- If you check this box, no signal will be sent to the API regarding the import. Checking the box will prevent external apps/API-based integrations from updating based on the import.

6. Start import button- Until fields are mapped, you will not be able to press this button. Fields must be mapped and a unique identifier must exist before the file can be imported.

Once you click the Start import button, the file is loaded into the import queue. A nation can import one file at a time.

Use settings again

Once an import starts, its field mapping is saved and can be re-used. When you upload a new file, you can use the "Use settings from a previous import"  dropdown to apply the saved field mapping. 

In the dropdown box, select a previously imported file.

Once a file is selected, the fields will be mapped. This assumes that the file being imported has the exact same layout as the previous import. You can adjust any discrepancies in field mapping between the current and previous imports. 

The options selected in the "Customize your import" section will also be filled in based on the previous import. 

Reusing settings is available for one-time, voter, vote history, donation, and membership imports. Each type of import saves settings from previous imports. The mapping cannot be shared between different types of import, e.g. you cannot use a previous donation import's settings in a membership import. 

Status of imports

After clicking the Start import button, a file is added to the import queue. The status displayed with that file will be "Queued for importing, but not started yet. Refresh to check."

Once an import starts, the status will change to "importing" or "working." Information available includes:

  • Completion percentage for an in-progress import.
  • Number of records processed.
  • Total number of records to process.
  • Estimated time until the import finishes.

If the estimated time to complete the import seems unusually long, email help@nationbuilder.com. The file may be unusually large and we may be able to help speed up the process.

Once an import finishes, the status will look like this:

Source: Click on the name and a copy of the imported CSV will download to your computer.

Size: The size of the imported file.

Added: Number of records added by the import. Clicking on the number takes you to a filter of the records created by the import.

Updated: Number of records updated by the import.

Errors: Number of errors detected in the import. The CSV error file will only contain the first 2 megabytes of errors. The last field in each record will contain the error logged. 

Time spent: Amount of time spent importing the file.

Status: When the import finished in relative time, or the current status of a queued / working import.

Imported addresses can take 24-48 hours hours to geocode. This aspect of the import status can be reviewed in Settings > Database > Geocoding services

Related HOWTOs

Types of imports
When imports overwrite existing data
How to avoid the 10 most common import mistakes
Recover from a bad import

Did this answer your question?