The membership feature is available to customers on the Team 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 People > 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 > People > Membership > New type 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.
Table of Contents
- Membership fields available
- Importing paid memberships
- Profile fields available
- Related HOWTOs
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.
|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.
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: firstname.lastname@example.org, Membership name: Silver, Status: active, Expires on: 1-1-2030
Line 3: Member email: email@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
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 firstname.lastname@example.org. Our Services team is available to help with this process.
There are three components to a paid membership:
- the supporter
- the membership record
- 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 objects 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.
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.
|country code||2 letter code from ISO 3166|
|Media market name|
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.
|ID||NationBuilder ID for recruiter|
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 another aspect of your nation. Most other field categories are actually sub-groupings of signup fields.
|donations to raise amount||Must have donor features enabled|
|assistant name or email||Must be a person who already exists in your nation|
|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.|
|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|
|external ID||Unique identifier|
|Facebook UID||Unique identifier, numerical ID for a Facebook user|
|Facebook username||Unique identifier, publicly visible Facebook username|
|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 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.|
|marital status||Single letter code for marital status|
|MeetUp ID||Unique identifier|
|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|
|PF Strat ID||Unique identifier, must have voter features enabled|
|point person name or email|
|recruiter name or email|
|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.|
|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|
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.
|country code||2 letter code from ISO 3166|