How to import memberships

The membership feature is available to customers on the Organization plan or above. The feature must be enabled in Settings > Defaults > Basics. To import memberships, a control panel user's permission set must include the ability to import people and manage memberships. 

Membership information can be imported from Settings > Defaults > Membership types > Import memberships.

On a technical level, a membership is a separate object from a profile or a donation within NationBuilder. Membership imports are assumed to have more accurate information than what exists within a nation - so when membership data is imported, it will always over-write existing membership information within a profile. Where possible, membership will be added to existing profiles. New people will be created if a unique identifier cannot match an existing person in your database. 

We recommend creating membership types in Settings > Defaults > Membership types before importing memberships. Doing this ensures that you can define a grace period for each type of membership.  

If this is your first time importing, please read how to prepare for your first import.


Membership

The primary focus of a membership import is to import membership data. Each line of data represents information on one membership type for one person or organization. In order to connect this data to the appropriate profile, you must also map a unique identifier for the member. The unique identifiers available in a membership import are listed within the profile fields section of this HOWTO.

Membership imports are assumed to be more accurate than data that already exists in your nation. This means that a membership import will always overwrite existing membership information. If the membership already exists on a profile, it will be updated by an import. This is true whether or not you check the box to overwrite existing data while preparing a membership import. That box only refers to profile fields. 

Field name Constrictions
expires on date - must be in the form MM/DD/YYYY
id numerical value defined by NationBuilder for the membership on the profile. Used when updating an existing membership. 
name membership type name
started at date membership began - must be in the form of MM/DD/YYYY
status active, canceled, expired, grace period. This field is case sensitive and can only accept these words in all lowercase. (E.g. "Active" will not be accepted.) 
status reason short reason for the current status of membership

Custom Fields cannot be updated or imported during the Membership Import. If you need to update or import custom fields you will need to also run a one-time people import.

 

Membership types:

If you import a membership name that does not already exist in your nation, a new membership type will be created. We strongly recommend creating the membership type in the Settings section of the control panel prior to importing membership data. Membership types created via import include a grace period of one day and there is no way to retroactively apply a different grace period.  

Membership ID is the unique identifier for a membership type created by NationBuilder. If you map to this field, you must refer to a type that already exists. Learn more about membership ID as part of importing paid memberships below.  

Status and expiration date:

The expiration date for an expired, canceled, or grace period membership must be today or in the past. An error will occur if the date is in the future.

Active memberships cannot be imported with an expiration date in the past. 

If your import includes historical and current membership information, you need to pay attention to the order of the information. For example:

Line 2: Member email: john@example.com, Membership name: Silver, Status: active, Expires on: 1-1-2030

Line 3: Member email: john@example.com, Membership name: Silver, Status: expired, Expires on: 1-1-2015

If this data was imported in this order, John's Silver membership would be updated twice: first to an active state, then to an expired state. To avoid this error, we recommend sorting by expiration date, with the oldest expiration date as the first row of data. By sorting your data before importing it, you will ensure that active memberships are not overwritten by historical data.


Importing paid memberships is complicated because it always requires importing the membership information separately from the payment information. These imports are connected using the membership ID assigned by NationBuilder.

If you find it difficult to follow these instructions, please email help@nationbuilder.com. Our Services team is available to help with this process.

There are three components to a paid membership:

  1. the supporter
  2. the membership record
  3. a donation

Technically, each of these components exists as a separate object within your nation’s database and is connected using unique identifiers. A donation is connected to a membership by the membership ID. This numerical value is assigned by NationBuilder when a membership is added to a profile and will not exist in your historical data. Remember: you cannot arbitrarily assign a number as the membership ID for a membership type. It must be created automatically within your nation.

When importing paid memberships, the membership information must be imported first. Then, the payment is imported separately. These two imports are connected using the membership ID.

Import the membership information, then export the memberships to see the membership IDs (option one).

For small imports, you can connect the two object in your control panel (option two). 

Option one: import, export, import

Import the membership information. Then, you can export your membership information to see the membership ID. A single profile can have many membership types. A membership ID matches a particular profile to a particular type of membership. You will need to connect this export to your transaction records and attach the membership ID to the transaction records. In Excel, this can be done using VLOOKUP

A single export does not exist for all memberships in a nation. Instead, a separate CSV can be downloaded for each membership type.

Then, import the donations.

Option two: import, import, edit donations in control panel

If you are importing a small number of paid memberships, you can import the membership information and import corresponding donations without the membership ID. Then, within your control panel, you will need to edit each donation record to associate it with the appropriate membership ID.

It is possible to view a list of all donations imported from a single file in the Finances section. Since you will need a membership ID that is unique to each member, it is better to go to the People section and in single-person view find the membership ID. Then, you'll go to the finances section with that supporter's profile and edit the donation transaction. 


Profile fields available in a membership import

A member can be a person or organization. Both people and organizations exist as profiles in the People section of your nation. Within the code, they are referred to as a "signup." The categories of fields in this section all exist within a profile. You will need to import a unique identifier listed within the Signup category to connect membership details to a member.

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. This is particularly true to the ID field - which is a unique identifier created by NationBuilder and is a numerical value referring to either the membership type, the recruiter, or the member.

Please review how address imports affect existing addresses prior to your first import. 


Address

This category refers to a person's home address. If you are importing an organization's membership data, do not use this field. An organization's address must be mapped to the work address

Field name Constrictions
address1  
address2  
address3  
city  
country  
country code 2 letter code from ISO 3166
county  
FIPS  
state  
zip  

Mailing address 

Field name Constrictions
address 1  
address 2  
address 3  

carrier route

 
city  
country  
country code  
county  
delivery point  
FIPS  
lot  
sort sequence  
state  
street name  
street number  
street prefix  
street suffix  
street type  
unit number  
zip  
zip 4  
zip 5  

Media market

Field name Constrictions
Media market name  

Precinct

Field name Constrictions
Precinct code  
Precinct name  

Recruiter 

The recruiter is the person who recruited the person to join your organization. Since this category appears in alphabetical order before the Signup category, be careful when mapping fields. The member's name and email should be mapped within the Signup category.

Field name Constrictions
email  
first name  
ID NationBuilder ID for recruiter
last name  

Registered address

Field name Constrictions
address 1  
address 2  
address 3  

carrier route

 
city  
country  
country code  
county  
delivery point  
FIPS  
lot  
sort sequence  
state  
street name  
street number  
street prefix  
street suffix  
street type  
unit number  
zip  
zip 4  
zip 5  

Signup

When importing memberships, the person or organization who is a member or your nation is the signup. Be careful when mapping first name, last name, and email of the member that you map those fields within the Signup category rather than the Recruiter category.

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. 

Field name Constrictions
donations to raise amount Must have donor features enabled
assistant name or email Must be a person who already exists in your nation
availability   
background   
church   
CiviCRM ID Unique identifier
county file ID  If you have voter features enabled, a county ID is a unique identifier. May be non-zero filled state ID in some states and must also map state and county.
created at Date joined or imported to nation - must be in the form MM/DD/YYYY
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
donations to raise amount in cents  Must have donor features enabled
dw_id If you have voter features enabled, Catalysts ID is a unique identifier.
email Must contain valid email address (can be repeated up to four times per profile)
email opt in  Y/N - opted into receiving email from your nation
employer   
ethnicity   
external ID  Unique identifier
Facebook UID  Unique identifier, numerical ID for a Facebook user
Facebook username  Unique identifier, publicly visible Facebook username
fax number   
federal do not call   
first name  Use with last name field or enter full name in "name" field
ID  NationBuilder ID, person's unique identifier auto-generated within your nation 
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 - must have donor features enabled
is ignore donation limits  Y/N - must have donor features enabled
is mobile bad  Y/N - indicates mobile number is bad and will not accept text messages
is volunteer  Y/N - must have volunteer features enabled
language  Primary spoken language - abbreviation code required
last name  Use with first name field or enter full name in "name" field.
legal name   
marital status   Single letter code for marital status
MeetUp ID   Unique identifier
middle name   
mobile number   
mobile opt in   Y/N - Willing to receive text messages from nation.
name   First name and last name in one field. Either map this field or map first name and last name fields.
NBEC GUID  Unique identifier, must have voter features enabled 
NGP ID  Unique identifier, must have voter features enabled 
occupation   
parent ID   
party  
party member   
PF Strat ID  Unique identifier, must have voter features enabled
phone number   
point person name or email   
prefix   
priority level   
recruiter name or email  
registered at   
religion   
RNC ID  Unique identifier, must have voter features enabled
RNC RegID  Unique identifier, must have voter features enabled
Salesforce ID  Unique identifier
sex  Must be M, F, or O (male, female, or other)
state file ID  Unique identifier, must have voter features enabled. 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
tag list  Currently, it is not possible to import tags when importing memberships. If you map to this field, the membership import will not complete. We recommend importing tags separately using a one-time import at People > More > Import.

List of tags separated by commas. Can map more than one field to tag list. See overwrite non-blank fields FAQ for additional information.
Twitter ID  Unique identifer
Twitter login Unique identifier
VAN ID  Unique identifier, must have voter features enabled 
website  Must be a valid URL. One address per profile.
work phone number   

Work address

This is the main address for an organization. An organization cannot have a home address. A person can have both a home address and a work address.

Field name Constrictions
address1  
address2  
address3  
city  
country  
country code 2 letter code from ISO 3166
county  
FIPS  
state  
zip   

How to create memberships

How to charge for memberships

Prepare for your first import

Importing addresses

How to import

 

 

 

Known issues:

Cannot complete a membership import with tags 

Cannot include custom fields in membership import

 

 

Do you like this page?

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.