How to import donations

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

If you would like to import paid memberships, invoices, or expenditures, please email help@nationbuilder.com to request a custom data import from our Services team.


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.

Field name Description
Billing address address1  
Billing address city Part of the address where the donation was billed.
Billing address state Part of the address where the donation was billed.
Billing address zip Part of the address where the donation was billed.
Signup email Donor’s email address. Field must contain a valid email address with correct formatting.
Signup first_name Donor’s first name
Signup last_name Donor’s last name
amount  
succeeded_at  
tracking_code_slug  Tracking code to aggregate donations. These do not have to exist in your nation, prior to completing a donation import

Donation

This category is only available when doing a donation import.  

Field name Description
actblue_order_number An ID for the donation created by ActBlue. Only map to this field if you are importing from ActBlue.
amount 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
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  
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  
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  
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, zip5, or country code.

Field name Description
address1  
address2  
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.

Field name Description
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.

Field name Description
id 1 of 10 valid payment IDs.
name 1 of 10 valid payment names.
ngp_code 1 of 9 valid payment ngp codes.

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.

Field name Description
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.

Field name Description
address1  
address2  
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 other aspect of your nation. Donations from organizations can be imported by including the signup type field.

Field name Description
Donations to raise amount  
assistant_name_or_email Must be a person who already exists in your nation.
availability  
background The note field that appears at the top of a profile. Only one background per profile. Distinct from the note that can be attached to a donation record.
church  
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 Date profile created or imported to nation - 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 A unique ID.
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  
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  
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_donotcall Y/N - registered on the U.S. federal do not call list.
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 to the organization name to the last name field. 
id* NationBuilder ID, a unique identifier auto-generated within your nation. Map to this field to accurately connect donation history to existing profiles in 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 - you must enable donor features to display within your nation.
is_ignore_donation_limits Y/N - you must enable donor features to use.
is_mobile_bad Y/N - indicates mobile number is bad and will not accept text messages.
is_volunteer Y/N - you must enable volunteer features 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  
marital status Single letter code for marital status.
meetup_id* Unique identifier
middle_name Map this field with the first name and last name fields. If importing middle names, do not use the name field. 
mobile_number  
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* Unique identifier
ngp_contact_id* Unique identifier for the donor. Distinct from NGP ID, which is a unique identifier for the donation.
occupation  
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  
point_person_name_or_email  
prefix  
priority_level Priority level is a number from 1-5. 1=lowest priority and 5=highest priority
recruiter_name_or_email 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* Unique identifier
rnc_regid* Unique identifier
salesforce_id* Unique identifier
sex Must be a single letter: M, F, or O (male, female, or other)
signup_type Indicates whether the donor is a person or an organization. Must be a single digit: 0 or 1 (0=person, 1=organization). If not specified, donors are assumed to be 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  
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. 
tag_list Recommend not importing a tag list during a donation import. If you map this field, the donor's tags will be overwritten by the tags imported.
twitter_id* Unique identifier, numerical ID from Twitter
twitter_login* Unique identifier, Twitter username - do not include the @ sign
van_id* Unique identifier
work_phone_number  

Signup profile

Field name Description
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, zip5, or country code.

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

Prepare for an import

Take a snapshot before importing

Unique identifiers

How importing affects existing data

How to map fields

Import codes

Primary address and importing addresses

Recover from a bad import

To add fundraiser to existing donations, signup fields must be overwritten by the import

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.