Prerequisites & Before You Begin

Last updated: March 30, 2026

Before enabling the Virtuous integration, there are a few things you need to set up in both Virtuous and WeGive. Completing these steps first will help you avoid sync errors, duplicate records, and integration locks down the road.

What You'll Need

Make sure you have the following before getting started:

  • Admin access to Virtuous CRM with permission to generate API keys and create custom fields

  • Admin access to your WeGive dashboard

  • Your Virtuous API Key (generated from your Virtuous admin settings)

  • Your Default Communication ID from Virtuous

Create the wg_id Custom Field in Virtuous

This step is required. WeGive uses a custom field called wg_id on the Gift object in Virtuous to track which gifts have already been synced. Without this field, WeGive has no way to match existing gifts, which leads to duplicate gift records appearing in Virtuous every time a sync runs.

To create it:

  1. In Virtuous, navigate to Custom Fields

  2. Click Create Field

  3. Select Gift as the object type

  4. Enter wg_id as the field name

  5. Set the field type to Text

  6. Click Save Field

Do not rename or modify this field after creating it. The integration depends on the exact name wg_id to function correctly.

Remove Unsupported Recurring Frequencies

Virtuous only supports a specific set of recurring donation frequencies. If any of your WeGive checkouts offer frequencies that Virtuous does not support, those recurring donations will fail to sync.

Supported frequencies: Monthly, Biweekly, Quarterly, Yearly, Daily, First and 15th

Not supported: Weekly, Semi-annually

To remove unsupported frequencies from your checkouts:

  1. In WeGive, go to Elements > Checkouts

  2. Edit each checkout that offers recurring giving

  3. In the Recurring section, uncheck Weekly and Semi-annually

  4. Save your changes

Repeat this for every active checkout. Any existing recurring plans using unsupported frequencies will not sync to Virtuous.

Clean Up Duplicate Emails in Virtuous

Virtuous previously allowed multiple contacts to share the same email address, but that is no longer the case. However, if your Virtuous data was created during that earlier period, you may still have duplicate emails in your system. The integration will return an error and fail to sync any donor whose email conflicts with another contact in Virtuous.

This most commonly happens when an individual donor and a company donor share the same email address. For example, a staff member's personal email might also be listed on their organization's contact record.

How to clean this up:

  1. In Virtuous, run a report or audit to identify contacts that share the same email address, especially between individual and company records

  2. For each conflict, remove the shared email from the company donor record. It is fine to leave the email field blank on the company record.

  3. In WeGive, add the individual as a Donor Portal Login on the company supporter so they still have access to manage the company's giving. Go to the company donor record, open the Actions tab, and select Add Login. Enter the individual's name, email, and phone number.

This keeps the individual's email on their own record (where it belongs) while still giving them access to the company supporter through the portal.

Prevent Duplicate Emails Going Forward

After your initial cleanup and data migration, take a few steps to keep duplicate emails from creeping back in:

  • Train staff to always search for an existing donor before creating a new record. A quick search by email can prevent most duplicates.

  • Periodically audit your donor database for duplicate email addresses. Catching them early avoids sync errors later.

If a donor's email is updated in WeGive to an address that already belongs to another contact in Virtuous, the sync will fail for that record and eventually create an integration lock after three retries. Keeping emails unique across your donor records is the best way to avoid this.

Test in Your Test Dashboard First

Before enabling the integration in your production environment, we recommend running through the setup in your WeGive Test Dashboard. This lets you verify that your API key works, your field mappings look correct, and your data syncs as expected without any risk to your live data.

Next Steps

Once you've completed these prerequisites, you're ready to connect the integration. See Connecting WeGive to Virtuous for the step-by-step setup walkthrough.