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

Table of Contents

Where to start

You must enable donation features in order to import donations. To begin importing donations, go to Finances > More > Import donations.

Donations can be attributed to a person or to an organization. A donation import can do two things:

  1. Add donation records to people / organizations who already exist in your database.
  2. Create a new profile for the donor and a new donation record.

Individual donation transactions can be imported. While it is possible to import the monthly transactions associated with a recurring donation, it is not possible to indicate that the transactions are part of an ongoing commitment. 

If you are trying to import a list of donors without individual donation records, use the one-time import at People > More > Import > One-time import

Before you import

Detailed instructions are available on preparing for an import. Important highlights:

  1. If you already have data in your nation, take a snapshot before starting an import. The snapshot must finish before you begin the import.
  2. Make sure your file includes unique identifiers for the donors.
  3. Understand how importing affects existing data.
  4. Mapping fields ensures data isn't lost or stored incorrectly.
  5. Some fields only accept data in a particular format - pay attention to any restrictions indicated.

Fields available in donation import

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. 

Most frequently used

This category includes the fields most frequently used when importing donations. Other types of imports will list different fields in this category.

Donation

This category is only available when doing a donation import.  

📌 Note: Fields marked with an * below are required.

  • actblue_order_number: A unique ID for a donation created by ActBlue. Only map to this field if you are importing from ActBlue. Do not use if you are importing recurring donations.
  • amount* : Required field. Amount of donation in dollars and cents. Use a decimal point to separate dollars and cents. Do not include currency symbol. Can also import other currency.
  • amount_in_cents: Amount of donation in cents.
  • authorization: Authorization code from the credit card processor (unique identifier per transaction)
  • canceled_at: Date donation was canceled. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes). The importer will attempt to parse dates in other formats, but we cannot guarantee accuracy.
  • check_number: Numeric field.
  • created_at: Date donation record created in NationBuilder. We strongly recommend allowing the importer to automatically define this field as a record of when the import was created. If a donation record only has one date, we recommend mapping that date to the succeeded_at field.
  • custom fields: Custom donation fields will be listed in the donation category in alphabetical order by field name.
  • election_cycle: Election cycle when the donation will be applied. List of cycles will vary by nation and are created in Settings > Political > Election.
  • employer: Text field.
  • failed_at: Date donation failed. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes). The importer will attempt to parse dates in other formats, but we cannot guarantee accuracy.
  • fec_type_id: A numeral from 1-9 indicating the Federal Election Commission transaction type.
  • fec_type_name: The Federal Election Commission transaction type name.
  • fec_type_ngp_code: A letter indicating the Federal Election Commission transaction type.
  • first_name: Donor’s first name.
  • id: The NationBuilder ID for the donation itself. Map to this field to edit existing donations. If a donation does not exist in your database, this field must be left blank.
  • ip_address: The IP address of the donor at the time a donation is received.
  • is_private: Y/N Mark yes if the donor wants to remain anonymous and not have her contribution displayed on your website. Standard templates only show the name of a person who donated, not the exact amount of the donation.
  • last_name: Donor’s last name.
  • membership_id: The ID of the membership (which already exists in the nation) that the donation is applied to. Please email help@nationbuilder.com for help importing paid memberships.
  • ngp_id: The NGP ID of the donation being imported. Map to the ngp_contact_id field for the donor's NGP ID.
  • note: Background note for the donation - will be attached to the donation record, not to the donor's profile.
  • occupation: Text field.
  • page_slug: The page slug for a page within your nation's website where the donation was made. Must be a slug that exists in your nation. Can be used to attribute offline donations to an online progress bar.
  • succeeded_at: Date donation succeeded. Format should be "MM/DD/YYYY" or "MM/DD/YYYY hh:mm:ss" (without quotes). The importer will attempt to parse dates in other formats, but we cannot guarantee accuracy. If your import only has one date per transaction, we recommend mapping to this field.
  • tracking_code_slug: Tracking code to aggregate donations. These do not have to exist in your nation, prior to completing a donation import.

Billing Address

When a donation is processed, the billing address for the credit card. Often, this is the only address included in a donation record.

One of these fields must be included in the import for the billing address to be created: address1, street name, city, zip, or country code.

  • 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

Election period

The election period during which the donation occurred. Must used one of seven names or codes.

  • Election period name: 1 of 7 pre-defined election period names.
  • ngp_code: 1 of 7 pre-defined single letter election period codes.

Payment type

These fields indicate how payment was received.

Recruiter

The person who introduced your nation. A profile for the recruiter must already exist in your nation. All fields within this category refer to the recruiter. To ensure the correct person is credited with recruiting the person, try to use the recruiter's email address or NationBuilder ID. 

In a donation import, the recruiter category is listed twice. While this is confusing, please be aware that the categories are distinct. The first recruiter category is for the person who introduced your nation. The second recruiter category is for the donation's fundraiser. Recruiters and fundraisers must have profiles in your nation before the import begins.

During a donation import, if you map to only one set of recruiter fields, the person will be listed as both recruiter and fundraiser. This is true regardless of which category you map. This will happen on profiles created through the donation import and on existing profiles that do not list a recruiter. If you check the box next to "overwrite existing data," this will also happen on existing profiles with a recruiter. If you are updating donation records, you must check the box to overwrite existing data to submit fundraiser information. 

If you map to both categories, you can import a recruiter and a fundraiser for each donation. If a donation is imported without a fundraiser, the donor will be listed as the fundraiser.

  • email: A valid email address already attached to the recruiter's profile.
  • first_name: The recruiter's first name, as it exists in your nation. Should also map recruiter's last name.
  • id: The recruiter's NationBuilder ID.
  • last_name: The recruiter's last name, as it exists in your nation. Should also map recruiter's first name.

Registered address

The address where the donor is registered to vote.

One of these fields must be included in the import for the registered address to be created: address1, street name, city, or country code.

  • 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

Signup

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. Donations from organizations can be imported by including the signup type field.

📌 Note: Fields marked with an * below are unique identifiers.

  • 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.
  • civiCRM ID* : Unique identifier.
  • 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.
  • 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: Text field.
  • 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.
  • twitter_id* : Unique identifier, numerical ID from Twitter.
  • twitter_login* : Unique identifier, Twitter username - do not include the @ sign.
  • van_id* : Text field.
  • work_phone_number: Numeric field.

Signup profile

  • website: Must be a valid URL. One address per donor.

Work address

Physical location of an organization or person’s work address.

One of these fields must be included in the import for the work address to be created: address1, street name, city, zip, or country code.

  • 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

Related HOWTOs

Prepare for an import
Take a snapshot before importing
Unique identifiers
How importing affects existing data
Import codes
Primary address and importing addresses
Recover from a bad import
Import donations (old)

Did this answer your question?