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:
- Add donation records to people / organizations who already exist in your database.
- 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 firstname.lastname@example.org to request a custom data import from our Services team.
Table of Contents
Before you import
Detailed instructions are available on preparing for an import. Important highlights:
- If you already have data in your nation, take a snapshot before starting an import. The snapshot must finish before you begin the import.
- Make sure your file includes unique identifiers for the donors.
- Understand how importing affects existing data.
- Mapping fields ensures data isn't lost or stored incorrectly.
- 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
- Billing address
- Election period
- Payment type
- Registered address
- Signup profile
- Work address
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.
|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|
|tracking_code_slug||Tracking code to aggregate donations. These do not have to exist in your nation, prior to completing a donation import|
This category is only available when doing a donation import.
|actblue_order_number||An 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.|
|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.|
|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 email@example.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.|
|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.|
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.
|country_code||2 letter code from ISO 3166|
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.|
These fields indicate how payment was received.
|id||1 of 10 valid payment IDs.|
|name||1 of 10 valid payment names.|
|ngp_code||1 of 10 valid payment ngp codes.|
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.
|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.|
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.
|country_code||2 letter code from ISO 3166|
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.
|Donations to raise amount|
|assistant_name_or_email||Must be a person who already exists in your nation.|
|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.|
|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.|
|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.|
|facebook_uid*||Unique identifier, numerical ID for a Facebook user|
|facebook_username*||Unique identifier, publicly visible Facebook username|
|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_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.|
|marital status||Single letter code for marital status.|
|middle_name||Map this field with the first name and last name fields. If importing middle names, do not use the name field.|
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.|
|ngp_contact_id*||Unique identifier for the donor. Distinct from NGP ID, which is a unique identifier for the donation.|
|parent_id||The NationBuilder ID of the profile's point person.|
|party||Single letter abbreviation for political party.|
|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.|
|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.|
|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|
|website||Must be a valid URL. One address per donor.|
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.
|country_code||2 letter code from ISO 3166|