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.
The Constituent Identifiers page provides a downloadable template and will automatically zero‑pad IDs when necessary.

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.

Using the correct tool will keep your import history organized and ensure reliable gift-to-constituent matching.

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

Adding additional email addresses for enhanced constituent matching

You can upload CSV files with extra email-to-constituent ID mappings to improve gift matching. This ensures that if donors use different email addresses, their records are accurately linked.

To upload these mappings, navigate to Online Giving > Reporting > Settings > Constituent Identifiers. In this section, upload a CSV file formatted with two columns: the constituent ID in the first column and the corresponding email address in the second column.

Ensure your CSV headers meet the expected format and record any changes to your constituent ID mappings for future reference.

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

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:

Navigate to Online Giving > Reporting > Settings > Constituent Identifiers. This interface is separate from 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.

Tips:

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.
Go to Reporting > Constituent Identifiers and search for that email address, or download the CSV template to review your data.
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
- The Constituent Identifiers page (Online Giving > Reporting > Settings > Constituent Identifiers) is specifically an email-to-external-ID mapping table. 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 page only displays External ID and Email address columns. It is a simplified mapping interface and does not attempt to show every attribute stored about an email.
- 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.

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
Run during off-hours to minimize impact on live reporting
Verify results in your gift reports after backfilling completes
Document changes you've made to constituent ID mappings