Virtuous CRM basic integration
Set up Fundraise Up’s integration with Virtuous CRM.
Virtuous is a CRM platform built to help organizations manage their supporters. Fundraise Up offers two integration methods to connect with Virtuous:
- Virtuous CRM (described in this article) offers a basic integration that syncs donation data to Virtuous in real time. However, it has several limitations that can impact data accuracy and flexibility.
- Virtuous G&C Import Write is a more advanced integration that uses Virtuous’s Import Tool to give you greater control and flexibility. This is the recommended method for most organizations.
Limitations of the basic integration
Before using the basic Virtuous integration, consider the following limitations:
- Recurring plan changes aren't synced. Due to API limitations, Fundraise Up can’t send updates to recurring payment schedules. As a result, if you enable the Track payments option, a recurring donation may appear as Past Due even if payments are being made on time.
- Supporter matching is automatic. Fundraise Up automatically matches donations to existing contacts using email, phone number, or address — depending on your integration settings. You can’t change this logic or customize the matching method. With G&C Import Write, you can use Virtuous’s Import Tool to manage duplicates more precisely.
- Rate limits apply. The basic integration supports up to 1,500 requests per hour from a single IP address. High-volume organizations may see sync delays during peak donation periods.
Recommended upgrade
If you’re using the basic integration, we recommend switching to Virtuous G&C Import Write. It provides more reliable syncing, flexible matching, and better data handling overall. You can connect to this integration directly from your Dashboard.
How the basic integration works
Here's how the basic Virtuous integration handles different types of data.
Recurring plans
Recurring plans in Fundraise Up sync to Virtuous as Recurring Gifts. Each plan has a one-to-one match, and each installment syncs as part of that gift.
When a recurring plan’s amount changes, or when a plan is canceled and later reactivated, Fundraise Up deletes and recreates the Recurring Gift in Virtuous. This keeps data consistent but may affect reports that rely on the original creation date of recurring gifts.
Contact matching and deduplication
By default, the integration matches each donation to a contact in Virtuous using the email address provided at checkout. If a match is found, the donation is linked to that contact. If not, a new contact is created.
You can choose alternate matching logic, such as “name and address” or “name and phone number”. This is useful if your organization collects different types of contact information. To configure this, go to the General settings tab of the integration and select the Match contact option.
Settings for selecting the Match contact type
Refunded donations
When you refund a donation in Fundraise Up, the integration updates the existing gift record in Virtuous instead of creating a separate refund. It changes the Gift Type to Reversing Transaction, keeping a clear audit trail.
Multiple currencies
Virtuous supports multiple currencies and works with Fundraise Up’s multi-currency setup.
Donations sync in both the original currency and your account’s default currency. To display both values, use these mapping rules:
Fundraise Up property | Virtuous property |
---|---|
donation → amount | gift → amount |
donation → currency | gift → currencyCode |
If you want to convert all donations into the default currency before syncing, use this setup instead:
Fundraise Up property | Virtuous property |
---|---|
donation → converted amount ([account currency]) | gift → amount |
account → default currency ([account currency]) | gift → currencyCode |
Configure general settings
You can control how the integration syncs data using several optional settings:
- Sync test data: Sends test-mode donations to Virtuous. Use this to validate your mapping rules before syncing real data. Disabled by default.
- Sync subaccounts: Appears only in parent accounts. When enabled, subaccount data syncs to Virtuous even if those subaccounts don’t have their own connection. Useful for chapter-based or federated organizations.
- Track payments (in Virtuous CRM): Lets Virtuous generate a schedule of expected payments for recurring gifts. This helps monitor balances and identify missed payments. However, because the basic integration does not sync recurring plan updates, Virtuous may display inaccurate statuses.
- Gifts are tax deductible: Marks all synced donations as tax-deductible in Virtuous. Enable this option if your organization classifies donations as tax-deductible for supporters.
General settings tab
- Default project: Sets the default project for synced donations. Values are pulled from your Virtuous account.
- Match contact: Controls how the integration identifies existing donors in Virtuous. You can choose from four options:
- By email: Matches donors by email address only.
- By email or name (default): Matches donors if either the email or name matches.
- By email or address: Matches donors if either the email or physical address matches.
- By email or phone: Matches donors if either the email or phone matches.
- Supporter phone type: Defines which phone field in Virtuous is used for supporter records (for example, Mobile or Home).
- Default segment: Sets the default segment for synced donations. Values are pulled from your Virtuous account.
- Default comment: Adds a fixed comment that is always included with synced donations.
Set up mapping rules
Mapping rules define how Fundraise Up data is written to Virtuous. You can map any supported Fundraise Up object and property to its counterpart in Virtuous. Default rules are provided, but you can edit or delete them as needed.
- Example: Designation mapping
Fundraise Up Virtuous Object: Designation Object: Project Property: Designation code Property: Code - Example: Custom question mapping
Fundraise Up Virtuous Object: Checkout question Object: Contact custom fields Property: How did you learn about us? Property: How did you learn about us?
Mapping rules are configured in the Mapping rules tab of the integration.
Mapping rules tab
To add a mapping:
- Scroll to the bottom of the mapping rules table.
- Click Add rule.
- Select the Fundraise Up object (entity) and property (field) on the left.
- Select the corresponding Virtuous entity and field on the right.
- Save your changes.
Default mapping
Some mappings are set by default and can’t be changed. These include:
Contacts → Household info
Virtuous property | Fundraise Up mapping behavior |
---|---|
Contact Type | Sets this value to Household by default |
Name | Combines the supporter’s first and last name |
On Behalf Of | If the Donate as organization option is used, sets this value as the organization name and changes Contact Type to Organization |
Informal Name | Inserts the supporter’s first name |
Primary Phone (Home Phone) | Inserts the supporter’s phone number (if provided) |
Primary Email (Home Email) | Inserts the supporter’s email address |
Address Line 1 | Inserts the first line of the supporter’s address (if provided) |
Address Line 2 | Inserts the second line of the supporter’s address (if provided) |
City | Inserts the city from the supporter’s address (if provided) |
State/Province/Region | Inserts the state, province, or region from the supporter’s address (if provided) |
Postal Code | Inserts the postal code from the supporter’s address (if provided) |
Country | Inserts the country from the supporter’s address (if provided) |
Gift → Gift details
Virtuous property | Fundraise Up mapping behavior |
---|---|
Gift Type | Sets to Credit for card payments, Electronic Funds Transfer for bank payments, and Other for all other methods |
Transaction ID | Inserts the donation ID |
Amount | Inserts the donation amount |
Gift date | Inserts the donation success date |
Receipt date | Inserts the internal timestamp from the receiptSentAt field |
Private | Writes value from the Anonymous donation setting (true if selected; false is not) |
Recurring Gift → Recurring Gift details
Virtuous property | Fundraise Up mapping behavior |
---|---|
Amount | Inserts the recurring donation amount |
Frequency | Sets the frequency if it is Weekly, Bimonthly, Monthly, Quarterly, Semiannual, or Annual. If the frequency is Daily, Biweekly, or Every 4 weeks, syncs as a one-time donation |
Start Date | Inserts the success date of the first donation |
Next Payment Date | Inserts the next donation date |
Private | Writes value from the Anonymous donation setting (true if selected; false is not) |
Configure special rules
Special rules let you apply conditional logic — for example, syncing a specific value only when certain criteria are met.
These special rules use "if/then" logic: If X happens in Fundraise Up, map the value as Y in Virtuous. They’re useful for cases like campaign-based mapping.
For example:
- If Campaign equals “Shelter” in Fundraise Up → set Project to “Shelter” in Virtuous.
- If designation equals "Areas of Greatest Need" in Fundraise Up → set the segment in Virtuous to "General Giving Audience."
Special rules are configured in the Special rules tab of the integration.
To add a special rule:
- Go to the Special rules tab.
Special rules tab
- Click Add Rule.
- Choose the Fundraise Up condition (IF) next to the Fundraise Up logo.
- Set the Virtuous mapping result (THEN) next to the Virtuous logo.
- Save your changes.
Sync settings
You can control how records sync between Fundraise Up and Virtuous. Sync options are located at the bottom of the Virtuous integration page in your Dashboard.
Sync options
Automatic sync (recommended)
By default, automatic sync is disabled when you first connect Virtuous. This lets you finalize mapping rules and configuration before any data is transferred.
Once enabled:
- New donations sync to Virtuous in real time.
- Updates to records in Fundraise Up (for example, donation metadata or recurring plans) are reflected in Virtuous according to your mapping rules.
We recommend enabling automatic sync.
Manual sync
Use manual sync if you need more control over when and what data is synced:
- Sync specific time ranges or your full donation history.
- Update previously synced records after adjusting mapping rules.
- Test your integration settings with controlled data transfers.
- Make bulk corrections when fixing outdated field mappings.
Sync log
The sync log provides a history of data sync activity between Fundraise Up and Virtuous. It shows which records were processed, whether they synced successfully, and any errors that occurred.
To view the sync log:
- Go to the Virtuous integration settings in your Dashboard.
- Scroll to the Synced donations section.
Synced donations section
Each log entry includes:
- The time and date of the sync.
- Records that were processed.
- Success or failure status.
- Error messages, if any — helpful for troubleshooting.
- A button to resync individual records if needed.
Troubleshooting
If you experience issues with the Virtuous integration:
- Check the sync log for error messages and failed sync attempts.
- Review your mapping rules to confirm that all required fields are configured correctly. Understanding Virtuous Mapping Rules in Fundraise Up →
- Check for recurring plan discrepancies if you’re using Virtuous’s Track payments option. The basic integration does not sync schedule changes for recurring plans, which may cause the schedule in Virtuous to fall out of sync over time.
- Review your organization’s email preferences if supporter records in Virtuous are showing as opted out. Why does Fundraise Up Virtuous integration always opt-out contacts from email →
- Confirm your rate limits. The Virtuous API allows up to 1,500 requests per hour per IP address. Exceeding this may result in sync delays or failures.
For persistent issues, contact Fundraise Up support with your sync log details.