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

 
Link copied

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

 
Link copied

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.

We recommend upgrading to Virtuous G&C Import Write for organizations currently using the basic Virtuous integration. You can connect to it directly from your Dashboard.

You cannot switch from Virtuous G&C Import Write to Virtuous basic integration.

Behavior

 
Link copied

Below, we describe some of the behavioral characteristics of the basic Virtuous integration.

Recurring plans

 
Link copied

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.

Virtuous doesn’t support 4-weekly recurring plans. If a recurring plan is created with “Every 4 weeks” as the frequency, donations will be synced to Virtuous individually as one-time donations.

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

 
Link copied

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

 
Link copied

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

 
Link copied

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

 
Link copied

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

 
Link copied

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

 
Link copied

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

 
Link copied

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

 
Link copied

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

 
Link copied

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?

 
Link copied

 

In this article