Constituent ID Backfill Tool

constituent identifiers vs. the school‑level data importer (sldi)

Before uploading files, confirm which tool meets your needs. The Constituent Identifiers upload and the School‑Level Data Importer (SLDI) are separate tools that maintain separate import histories.

school‑level data importer (sldi): Use SLDI for importing full constituent records with additional attributes (such as names, multiple emails, affiliations, class years, or custom fields). SLDI populates the detailed constituent data used by personalization features.
constituent identifiers upload: This is a lightweight, two‑column CSV workflow for bulk mapping an email address to an external constituent ID (email ↔ constituent ID). These mappings enable gift matching and are used by the Backfill tool to link historical gifts with constituent IDs.

Each tool maintains its own import history. Full constituent records uploaded via SLDI appear in the Data Importer history, while two‑column uploads appear on the Constituent Identifiers page. This separation prevents confusion when reviewing upload histories.

quick checklist — which upload should i use?

Mapping emails to external IDs only: Use the Constituent Identifiers upload with a two‑column CSV (Constituent ID, Email address).
Importing or updating full constituent records: Use the School‑Level Data Importer (SLDI) in the Data Import area.

csv requirements for constituent identifiers uploads

The file must have exactly two columns in this order: 1) Constituent ID, 2) Email address.

where each upload appears in the admin ui

sldi uploads: Appear in the Data Import section along with full import histories and validation errors.
constituent identifiers uploads: Appear on the Constituent Identifiers page with its own upload history and validation feedback.

practical tips and common gotchas

If a two‑column mapping upload isn’t visible in the Data Importer history, check the Constituent Identifiers page.
Run the Backfill tool (Backfill Constituent Identifiers) after uploading to apply mappings to historical gifts. The upload itself does not update past gifts.
Test using a small date range first to verify the results before backfilling a larger set of records.
Review gift records if many still appear in Gifts to Review; check for typos, extra spaces, or alternate domains in email addresses, then correct the mappings and run Backfill again.

What Backfilling Does

The Constituent ID Backfill tool updates existing donation records to include constituent identifiers when you've added or updated your constituent ID mappings after gifts were already processed.

When to Use Backfill

Use backfill when:

You've added new constituent ID ↔ email mappings
You've corrected existing constituent ID mappings
Existing gift records need updated constituent IDs for accurate reporting

How to Access the Tool

Navigation: Online Giving → Reporting → Constituent Identifiers → "Backfill Constituent Identifiers"

Navigate to Online Giving → Reporting → Constituent Identifiers. This interface is separate from the Data Importer.

The Constituent Identifiers page is an email-to-external-ID mapping table. It displays Email, External ID, Created, and a Delete option for each record. This simplified mapping interface is designed solely for managing email-to-ID associations and does not display every attribute of an email.

The page also includes an Add Individual Identifier form (located on the right side) where you can enter a single constituent email and constituent ID to create a one-off mapping without uploading a CSV file.

The Constituent Identifiers page includes a link to a Google Sheets template you can use as a formatting guide. IDs are automatically zero-padded according to your school’s configuration. In the same page, search for the relevant email address or click the template link to review your data.

Note: Leaving the days field blank defaults the backfill to the past 30 days.

Enter the number of days you want to backfill (how far back to update records)
Click "Backfill Constituent Identifiers"

The system will update donation records from the specified number of days back to today using your current constituent ID mappings.

Alternative method: Upload constituent IDs via Reporting > Settings

If you need to update constituent ID-to-email mappings only, follow these steps outside of the Data Importer:

Download the CSV template provided on the page. The template requires exactly two columns in this order:
- Constituent ID
- Email address
Fill in the CSV. If your school uses a standard ID length, uploaded IDs will be automatically zero-padded.
Upload your CSV on the Constituent Identifiers page.
Once the upload completes, click the "Backfill Constituent Identifiers" button to update the existing gift records with the new mappings.

Troubleshooting: why gifts appear in the "Gifts to Review" table and how to fix it

Gifts appear in the "Gifts to Review" table when a donor's email address does not match any constituent ID record. This usually happens because of missing or mismatched email-to-ID mappings.

Diagnosis and fix

Open a gift from the "Gifts to Review" table and note the donor's email address.
Confirm that the email in the gift record exactly matches the email in your constituent data. Look for extra spaces, typos, or domain differences (for example, donor@example.com vs donor@example.org).
If the mapping is missing or incorrect, upload an updated two-column CSV file (Constituent ID, Email address) via the Constituent Identifiers page and then run the backfill to update your records.

Additional tips

Test with a small date range first to confirm the changes are working as expected.
If many gifts appear in the review table, check your data for systemic gaps such as missing secondary or alternate emails.
After updating mappings and running backfill, verify that gift records now show the correct constituent IDs.
If the backfill links multiple emails to one constituent ID, review the source data for duplicates and correct them before re-running.

Repeat these steps with additional sample gifts to determine if the issue is isolated or more widespread.

Use this process for updating only constituent ID/email mappings; use the Data Importer for broader data operations.
Ensure the CSV columns remain in the correct order to avoid file validation errors.
Spot-check a few recent gift records after backfilling to confirm the updates were applied correctly.

What the Constituent Identifiers page shows — and what it doesn't
- Use this area to upload or download simple two-column mappings (Constituent ID ↔ Email address) that the backfill tool uses to link past gifts to your constituent IDs.
- The Constituent Identifiers interface is separate from full constituent management and is not meant to display all email attributes. Treat this screen as a lightweight mapping table for backfill and matching purposes, not as a full view of a constituent’s email records.
What the API supports for constituent emails
- The API supports email_type and primary fields for constituent emails (in addition to address). The API’s constituent email objects include the fields email_type, address, and primary.
- The primary and email_type values are stored in the system but not shown in this specific interface. In other words, those values exist in GiveCampus data and are returned by the API, but they are intentionally not surfaced on the Constituent Identifiers page.
How to verify or manage email_type and primary values
- If you need to confirm whether a given email is marked primary or what its email_type is, retrieve the constituent’s email data via the API; the emails array in the API response contains the address plus email_type and primary fields.
- Uploading a CSV on the Constituent Identifiers page only creates or updates the email ↔ external ID mapping (the two visible columns). It does not change email_type or primary flags. To change those attributes, use the API endpoints that accept constituent email objects.
Recommended workflow and common gotchas
- Use the Constituent Identifiers upload when your goal is bulk mapping of email addresses to external constituent IDs so the backfill tool can reconnect historical gifts to your IDs.
- After uploading mappings and running Backfill, verify results where necessary by either spot-checking gift records in the admin UI or inspecting the constituent email objects via the API to confirm email_type and primary as needed.
- Remember: a successful mapping upload may result in multiple emails linked to the same External ID; the Constituent Identifiers UI will still show only the External ID and Email address columns even when multiple rows share an ID. If you need a full picture of a constituent’s email attributes (for example, to decide which address is marked primary), check the API.

Troubleshooting CSV upload errors — extra empty columns

Hidden or trailing empty columns can cause a two‑column upload to fail. The Constituent Identifiers uploader requires exactly two columns in this order: 1) Constituent ID and 2) Email address. Even extra empty columns can cause the email address to be misinterpreted as blank, resulting in invalid rows during review.

Diagnose the issue

On the Constituent Identifiers page (heading: Constituent Identifiers, section Upload Multiple Identifiers), upload your CSV and proceed to the review step. If you see an error such as "We found some invalid rows in your CSV." with messages indicating that the email cell is invalid, extra columns are likely the cause.
Open your CSV in a plain text editor (such as Notepad or TextEdit). Each row should contain exactly two values separated by a single comma (for example: 12345,donor@example.com). Remove any trailing commas or extra commas that suggest more columns.
If your spreadsheet shows the email in the third column, that confirms an extra empty column. Adjust the file so that the email is in column 2 and save it as a CSV (UTF‑8 without BOM is recommended).

Fix and re-upload

Remove any extra columns in your spreadsheet by ensuring only column A (Constituent ID) and column B (Email) are present, then re-save as CSV. Alternatively, use a plain text editor to remove trailing commas so each line contains only one comma.
Re-upload the cleaned CSV on the Constituent Identifiers page and proceed to the review step. Rows with blank IDs or invalid email formats will be flagged.
When no invalid rows appear, click Approve to process your file. After a successful upload, run Backfill Constituent Identifiers for the desired date range.

Additional notes and best practices

Test with a small sample or a short date range to verify the file format and backfill behavior before uploading a larger file.
If your school uses a fixed external ID length, uploaded IDs are automatically zero‑padded during processing—you do not need to add padding in the CSV.
This uploader is solely for mapping Email ↔ Constituent ID. For importing full constituent records (names, multiple emails, affiliations, custom fields), use the School‑Level Data Importer (SLDI).
If errors persist after cleaning the file, check for invisible characters or non‑standard commas. Opening and re-saving the file in a plain text editor can resolve these issues.
After backfilling, spot‑check gift records to ensure the mappings are correctly applied and that gifts no longer appear in the "Gifts to Review" table.

Understanding Results

Multiple Records with Same ID

If backfilling results in multiple constituents sharing the same ID with different email addresses, this indicates:

Data inconsistency in your constituent ID mappings
Possible duplicate records in your database
Email changes for the same constituent over time

To resolve:

Review your source data to identify why multiple emails map to the same constituent ID
Clean up duplicate mappings in your database
Re-run backfill after corrections

Best Practices

Start small - Test with a few days first if you're unsure about mapping changes
Verify results by reviewing gift records after the backfill completes.