Virtuous basic integration
Set up Fundraise Up’s integration with Virtuous.
Virtuous is an all-in-one CRM platform designed to help nonprofit organizations streamline their supporter management processes. Fundraise Up offers two ways to integrate with Virtuous.
- The first option is a basic integration (simply called “Virtuous” in the Dashboard) that processes data in real time.
- The second option, which we recommend, is the advanced Virtuous G&C Import Write. This method uses Import Tool for a more flexible and comprehensive integration.
Limitations
Basic Virtuous integration have certain limitations that you should be aware of.
- Due to API limitations, we cannot update changes to recurring payment schedules. For example, a recurring gift (donation) with the “Track payments” option enabled in Virtuous will move to “Past due” status regardless of whether payments are received on time or late.
- Supporter matching takes place on our end: we match supporters based on email, phone number or address, depending on what the organization chooses in the integration settings. This process is automated. Virtuous G&C Import Write provides a more effective Import Tool for better supporter matching. This allows organizations to control the matching process themselves.
- The system enforces rate limits, with a maximum of 1,500 requests per hour from a single IP.
Virtuous G&C Import Write addresses all these issues. However, integration with Virtuous G&C Import Write requires some human input from the organization's side. An employee of an organization must match the data for new donations or recurring plans and click “Import” in Virtuous for updates to occur. Learn more in the Virtuous G&C Import Write documentation →
Switching to Virtuous G&C Import Write
Virtuous G&C Import Write is the default integration for any organization that has not previously used Virtuous. Such organizations will not see the option to connect to the basic Virtuous integration in the Dashboard.
You cannot switch from Virtuous G&C Import Write to Virtuous basic integration.
Behavior
Below, we describe some of the behavioral characteristics of the basic Virtuous integration.
Recurring plans
There is a one-to-one correlation between the Recurring Plans object in Fundraise Up and the Recurring Gifts object in Virtuous. When a recurring plan is created in Fundraise Up and synced to Virtuous, a recurring gift is created in Virtuous. Similarly, recurring plan installments in Fundraise Up are synced to corresponding installments in Virtuous.
When any of the following conditions are met, a recurring gift created by Fundraise Up in Virtuous is deleted and a new one is created:
- The donation amount for the recurring plan is changed in Fundraise Up
- The recurring plan is canceled and then reactivated in Fundraise Up
Constituent matching and deduplication
By default, the integration will attempt to match a donation record to a contact in Virtuous using the email address provided at checkout. If a match is found, the donation will be associated with the contact in Virtuous. If a match is not found, a new contact is created in Virtuous, and the donation record is associated with the new contact.
Alternatively, you can configure the integration to match records using one of the following combinations:
- Name and address
- Name and phone number
Refunded donations
If a donation is refunded in Fundraise Up, the Gift Type of the associated record in Virtuous is changed to Reversing Transaction.
Handling multiple currencies
Virtuous includes a feature for handling multiple currencies. This way, donations made using multiple currencies in Fundraise Up are synced to Virtuous without the need to convert values to the default currency in Virtuous.
You can view the amount in the original currency and the converted amount (in your default currency) in the Virtuous Gift details. The following rules must be configured to display the Amount field in the original currency amount and the Converted Amount field in the converted amount in the default currency. The conversions will then be done automatically.
| Fundraise Up property | Virtuous property |
|---|---|
| donation → amount | gift → amount |
| donation → currency | gift → currencyCode |
If you prefer to not support multiple currencies, you can configure the following mapping rule for the Virtuous integration in Fundraise Up.
| Fundraise Up property | Virtuous property |
|---|---|
| donation → converted amount ([account currency]) | gift → amount |
| account → default currency ([account currency]) | gift → currencyCode |
Configuration
These optional settings control basic integration functions.
- Syncing test data: When using test mode to experiment with platform settings, you can opt to send test transactions to Virtuous. This enables you to configure and refine mapping rules so that values from Fundraise Up are synced to the expected properties in Virtuous. By default, the Sync test data option is disabled when you enable an integration, but it can be enabled from the integration’s settings.
- Sync subaccounts: When the Subaccounts feature is enabled, you can opt to sync data from a primary account’s subaccounts to apps connected at the primary account level. This is useful for tracking donations and simplifying reporting when your organization uses a chapter-based or federated model.
- Track payments (in Virtuous CRM): When this setting is enabled, Virtuous generates a schedule of expected future payments for recurring gifts in Virtuous, which is useful for tracking outstanding balances or identifying late or missed payments.
Mapping rules
Use mapping rules to define the destination objects and properties of data values synced from the platform. Support for mapping rules is based on the flexibility of Virtuous’ API.
Mapping rules are configured by linking a Fundraise Up object and property to an object and property in Virtuous. A value sent from Fundraise Up will be written to a property in your Virtuous account. By default, Fundraise Up defines some rules for you to reduce the implementation steps you need to take. These rules can be removed or modified as needed.
Mapping rules examples:
- Linking the designation property from Fundraise Up to the project code property on the Contact object in Virtuous.
Fundraise Up Virtuous Object: Designation Object: Project Property: Designation code Property: code - Linking a custom question property in Fundraise Up to a custom question property in Virtuous.
Fundraise Up Virtuous Object: Checkout question Object: Contact custom fields Property: How did you learn about us? Property: How did you learn about us?
Special rules
The Virtuous integration can be configured to use special rules. These types of rules use if/then conditions that enable you to link a property’s value in Fundraise Up to a property’s value in Virtuous.
Special rule examples:
- If Campaign equals “Shelter” in Fundraise Up, then set the project in Virtuous to “Shelter.”
- If Designation equals “Areas of Greatest Need” in Fundraise Up, then set the segment in Virtuous to “General Giving Audience.”
Non-configurable mappings
In some cases, Fundraise Up sets mapping values that cannot be adjusted from the integration settings page. These mappings are described below.
Contacts → Household information
| Virtuous property | Fundraise Up mapping behavior |
|---|---|
| Contact Type | By default, sets the value to Household |
| Name | Inserts a concatenated form of the first and last name values from Fundraise Up |
| On Behalf Of | If the Donate as organization option is used, the value from Fundraise Up is written to the Name field in Virtuous and the Contact Type is set 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 from the supporter’s address (if provided) |
| Address Line 2 | Inserts the second line from 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 values from supporter’s address (if provided) |
| Postal Code | Inserts the postal code from supporter’s address (if provided) |
| Country | Inserts the country from a supporter’s address (if provided) |
Gift → Gift details
| Virtuous property | Fundraise Up mapping behavior |
|---|---|
| Gift Type | If a card payment method is used, the value is set to Credit. For bank-based methods, the value is set to Electronic Funds Transfer. For all other payment methods, the value is set to Other. |
| Transaction ID | Inputs the donation ID |
| Amount | Inputs the donation amount |
| Gift date | Inserts the donation date |
| Receipt date | Write the value of the internal property, receiptSentAt |
| Private | Writes the Boolean value of the Anonymous donation property. If the anonymous donation option is not used in Checkout, the value is false |
Recurring Gift → Recurring Gift details
| Virtuous property | Fundraise Up mapping behavior |
|---|---|
| Amount | Inserts the donation amount |
| Frequency | Sets the recurring plan frequency if the value is Weekly, Bimonthly, Monthly, Quarterly, Semiannual, or Annual. If the value is Daily, Biweekly or Every 4 weeks, the record is synced as a one-time donation. |
| Start Date | Inserts the success date of the donation |
| Next Payment Date | Inserts the Next Donation Date value |
| Private | Writes the Boolean value of the Anonymous donation property. If the anonymous donation option is not used in Checkout, the value is false |
Sync settings
Fundraise Up’s Virtuous integrations include settings for managing the sync behavior for records.
- Automatic sync: By default, the automatic sync option is disabled when you connect Fundraise Up to Virtuous. This enables you to configure the integration’s settings and mapping rules before synchronizing records.
Once you are satisfied with the configuration for an integration, we recommend enabling the automatic sync feature.
- Manual sync: This option is useful when you elect to not use the automatic sync function, or when you want to resync previous records.
- Resyncing previous records: When you make changes to record properties for past donations in Fundraise Up, you can use the manual sync option to update the associated records in Virtuous. This is beneficial for scenarios where an incorrect mapping was made in Fundraise Up.
- Sync period: When you manually sync records, you can opt to sync all records or specify date range. Narrowing the sync scope using a date range is useful when you need to target a specific set of records or want to avoid resyncing a significant number of records.
- Disconnect Virtuous: You can disconnect Virtuous at any time from its settings page. Disconnecting and then reconnecting Virtuous using the same credentials will preserve the settings and mapping rules set before Virtuous was disconnected form Fundraise Up.
Troubleshooting
Get help with common troubleshooting items and find answers to frequently asked questions about Virtuous.
🔗 Understanding Virtuous Mapping Rules in Fundraise Up
🔗 Why does Fundraise Up Virtuous integration always opt-out contacts from email?