📌 Note: Memberships and custom fields are available as an add-on. For more information on adding new features please see the add-ons page in your nation.

Where to start

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.

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.

These fields are also available for export

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.
memberships_started_at: Date - must be in the form MM/DD/YYYY this is the day their membership started
memberships_expires_on: Date - must be in the form MM/DD/YYYY this is the day their membership expires on
memberships_suspended_at: Date - must be in the form MM/DD/YYYY this is the day their membership entered the grace period

📌 Note: 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.

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: [email protected], Membership name: Silver, Status: active, Expires on: 1-1-2030

Line 3: Member email: [email protected], 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.

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 or export

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.

address1: Home address, first line (street number, street name, street prefix/suffice, street type).
address2: Home address, second line (unit number).
address3
city
country
country_code: 2 letter code from ISO 3166.
county
FIPS
state
zip

Mailing address

address1: Home address, first line (street number, street name, street prefix/suffice, street type).
address2: Home address, second line (unit number).
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: Last 4 digits of a Zip+4 code. Only to be used in conjunction with zip5 field.
zip5: First 5 digits of a Zip+4 code. Only to be used in conjunction with zip4 field.

Media market

media_market_name

Precinct

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.

email
first name
ID: NationBuilder ID for recruiter.
last name

Registered address

address1: Home address, first line (street number, street name, street prefix/suffice, street type).
address2: Home address, second line (unit number).
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: Last 4 digits of a Zip+4 code. Only to be used in conjunction with zip5 field.
zip5: First 5 digits of a Zip+4 code. Only to be used in conjunction with zip4 field.

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: Goal for person to fundraise.
assistant_name_or_email: Must be a person who already exists in your nation.
availability: Times available to volunteer.
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: Church maps to a field in your NationBuilder control panel called Place of Worship. Please note this field doesn't exist in some countries where collection of this type of data is not permitted under law.
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: We strongly recommend not importing to this field. Please allow the importer to define the date a record is created within your nation based on the date of the import. If imported, date 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.
datatrust_id* : Unique identifier.
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.
donations_to_raise_amount_in_cents: Numeric field.
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 first email mapped will be identified as the profile's primary email address.
email_opt_in: Y/N - opted into receiving email from your nation.
employer: Place of employment.
ethnicity: Open text field.
external_id* : Unique identifier.
facebook_uid* : Unique identifier, numerical ID for a Facebook user.
facebook_username* : Unique identifier, publicly visible Facebook username.
fax_number: Numeric Field.
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 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 have donor features enabled to display within your nation.
is_ignore_donation_limits: Y/N - you must have donor features enabled in your nation to use.
is_mobile_bad: Y/N - indicates mobile number is bad and will not accept text messages.
is_volunteer: Y/N - you must have volunteer features enabled 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: Text field.
marital_status: Single letter code for marital status.
meetup_id* : Text 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: Numeric field.
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* : NationBuilder Voter ID, unique identifier defined in the NationBuilder Voter File.
ngp_contact_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: Text field.
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: Numeric field.
point_person_name_or_email: Text field.
prefix: Text field.
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* : Text field.
rnc_regid* : Text field.
salesforce_id* : Text field.
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: Text field.
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.
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* : Text field.
ward: Political district only available in a voter file import.
website: Must be a valid URL. One address per record.
work_phone_number: Numeric field.

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.

address1: Home address, first line (street number, street name, street prefix/suffice, street type).
address2: Home address, second line (unit number).
address3
city
country
country_code: 2 letter code from ISO 3166.
county
FIPS
state
zip