Table of Contents
- What is a unique identifier?
- Signup IDs
- Importing data
- Donation IDs
- Membership IDs
- People without unique IDs
- Shared email address
What is a unique identifier?
A unique identifier (ID) is data that exists in only one profile within a nation. Think of it like a social security number: a particular value can only exist in that field in one record in your database. Unique IDs are used to merge information from imports with existing records in your nation and for deduping records in your nation. All imports must include a unique ID.
A profile represents a person or organization in your nation. Within the code, a profile is referred to as a signup.
A profile in NationBuilder has several options for unique IDs:
- email address
- Facebook username
- Twitter ID (numerical ID from Twitter)
- Twitter login
- Meetup ID
- CiviCRM ID
- Salesforce ID
- External ID
- NationBuilder ID (also known as signup ID)
Additionally, voters in your nation may have one or more of the following unique IDs:
- County file ID (with registered county and registered state)
- Data Trust ID
- DW_ID (also known as Catalist ID)
- Voter GUID (this is specific to NationBuilder)
- NGP ContactID
- PF Strat ID (also known as PoliticalFORCE ID)
- State file ID (with registered state)
- RNC ID
- RNC Registration ID
- VAN ID
During an import, all of the above IDs are listed in the signup category. NationBuilder ID is listed as "ID" within the signup category.
The state file ID will be considered a unique identifier if you also map the registered state field. If you want to use the state file ID to match an import to existing profiles, the people in your database must have a state listed in their registered address. This rule is in place because a nation can include people from multiple states and state file IDs are not unique across the country. The first time you import people, the registered state will be transformed into a two-letter code, corresponding to the expected two-letter designation based on ISO 3166-2 standards. Please take additional precautions to avoid creating duplicate profiles with subsequent imports with state file IDs.
Similarly, the county file ID will only be considered a unique identifier if you also map the registered county and registered state fields during import. And if you want to use the county file ID to match an import to existing profiles, the people in your database must have a county and a state listed in their registered address. This is because county file IDs are not unique across the country. Please take additional precautions to avoid creating duplicates on subsequent imports with county file IDs.
Once the import has finished newly imported people in the nation will have a NationBuilder ID assigned to them.
All imports must contain at least one unique ID per record.
📌 If a record is imported with a unique ID that already exist in the nation, the existing profile will be updated.
A specific unique ID can only exist in a single profile. An imported record will never create a new profile if the imported record includes an existing unique ID.
Duplicate profiles will be created if an import's particular unique ID cannot be found. Each unique ID field is separate. For example, if my nation includes a profile with "XYZ" Salesforce ID and I import a record with "XYZ" External ID, another profile will be created. It doesn't matter that the value is the same - the same value must exist in the same unique ID field for an import to be matched to an existing profile.
Importing voter file IDs can create duplicate profiles
When importing data and matching on state file ID or county file ID, there is a stronger possibility of creating duplicate profiles. There are two rules that need to be followed:
1. Always use a two-letter code for registered state, based on ISO 3166-2 standards. For example, Alberta should be imported as AB.
2. Always import registered county using the exact same spelling.
Even when your initial import includes registered state written as a word, the field will be transformed into a two-letter code when a voter profile is created. Subsequent imports must use the two-letter code in the registered state field. That is the only way a state file ID or county file ID will match the profile that already exists in your databse.
It is important to import registered county with consistent formatting and spelling. For example, if a profile exists with "Riverside County" in the registered county field, a subsequent import with "Riverside" listed in that field will create a duplicate profile when county file ID is included in the import.
See the Overwrite existing data HOWTO for information on how data conflicts between imports and existing profiles are handled.
Donations exist in a separate table from profile information. Donations have their own unique ID (donation_nationbuilder_id). When donations are imported, one of the above signup IDs is used to match the donation to its donor. Donation imports must include a signup ID.
If a donation import should update existing donation records in your Finances section, map the "ID" field within the donation category.
Memberships also exist in a separate table from profile information. The fields membership ID and membership name are unique IDs for each type of membership. We recommend using the membership ID field in imports. A membership name must match exactly - the imported membership name cannot include extra spaces and the letter-case must match an existing membership type exactly to be matched.
A membership record is connected to the member's profile using one of the above signup IDs. Membership imports must include a membership unique identifer and a signup ID. If the membership type does not already exist in the nation, it will be created.
People without unique IDs
On rare occasions, you may want to upload a list of people without a unique ID. Perhaps you have a list of people and physical addresses without any other identifying information. Rather than creating a fake ID, you can create a blank column for NationBuilder ID.
- Open the CSV file in Excel
- Insert a new column to the left of the existing columns
- Name that column "signup ID"
- Leave the rest of the column blank
- Save the CSV file
- Import your file mapping the new column to the "ID" field within the signup category
By following the steps above, the people will be imported into your nation and assigned a NationBuilder ID automatically. Remember - you cannot assign people a NationBuilder ID. It must be done automatically when a profile is created. It is always preferable to import people with a unique ID, rather than tricking the system into assigning one on import.
If you are having difficulty with an import, please email email@example.com for assistance.
Shared email address
It is possible that two or more people share an email address. Within a nation, that email address can only be connected to a single profile. Connect the email address to the person who primarily corresponds with the nation using that address. Create another profile for the second person using the address. Connect the profiles by creating a relationship between them. If the people share a physical address, householding will also connect their profiles.