Skip to content
English
Submit a Support Request
  • There are no suggestions because the search field is empty.

Setting Up Virtuous

How do I integrate with Virtuous?

This article guides through how to connect iDonate to Virtuous, configure settings, and manage the connection over time.

Prerequisites

Before beginning, make sure you have:

  1. Access to an iDonate Admin user.
  2. Admin access to your Virtuous account.

Connecting to Virtuous

In Virtuous

  1. Click Settings > All Settings > Connectivity > API Keys (not Application Keys).

    virtuous-api-key
  2. If needed, create a new API Key by clicking Create an API Key, set a Name and Permission Group, and Save.
  3. In the API Keys table, find the key you want to use and click the Edit button.

    virtuous-find-api-key
  4. Click the eye icon to display the API Key value and copy it.

API Keys serve as long-term credentials that remain active until manually revoked. Since they grant continuous access, it’s essential to keep them securely stored and avoid sharing them through email, chat, or any unsecured text files.

In iDonate

  1. After obtaining your Virtuous API Key, go to iDonate and navigate to Settings > Integrations.

  2. Click Virtuous from within the Marketplace which will open the Virtuous Config Wizard.
  3. Click Configure.
  4. On the Virtuous Connection page input your API Key and click Next.

    virtuous-connection

Configurations

The following configurations determine how data flows and behaves within your Virtuous integration. Review each setting carefully as they directly impact how information is processed and synced.

Processing

  1. Donor Fee Processor: Determines how donor fees are processed.
  2. Donor Fee Designation: The designation that will receive all donor covered fees. Required if "Donor Fee Processor" is set to "Standard". Defaults to "Standard".

Definitions

  1. Default Designation: When a donation occurs and does not have an associated designation, the export will use this designation when exporting to your CRM.
  2. Populate Receipt: Notifies Virtuous that a receipt has already been sent to a donor. Disabled by default.
  3. Segment Map: Determines if iDonate Campaigns or Reference Codes get mapped to Virtuous Segments. Defaults to Campaign.

Options

  1. Create Projects: When enabled, creates projects or designations that are not yet in Virtuous. Enabled by default.
  2. Label Donation Source as Beta: Optionally append Beta to the Virtuous Transaction Source for testing. When enabled, donations are sent to a separate batch, keeping test data distinct from live iDonate records. Disabled by default.

    virtuous-transaction-source-beta
  3. Group Donations by Currency: Optionally append currency code to the Virtuous Transaction Source, resulting in separate batches for each currency (e.g. USD vs. CAD). Disabled by default.

    virtuous-transaction-currency

After reconfiguring any settings in the Config Wizard, be sure to click Finish on the final step. Changes are only saved once you complete the wizard by selecting Finish.

For a detailed breakdown of how iDonate data maps to Virtuous objects and fields, see Virtuous Field Mapping. To pause or deactivate this integration, see Managing an Active Integration in Integrations Overview.

Virtuous Gift & Contact Importer

As donations are made through iDonate, that data is automatically sent to Virtuous, where it is processed in nightly batches. Each batch includes new gifts, recurring donations, and any new supporter profiles created since the previous batch. 

How batching works:

  1. Donations are received. As transactions occur in iDonate throughout the day, they are sent to Virtuous and held in the Pending Gifts table.
  2. Transactions are bundled into imports. Each night Virtuous groups the pending transactions into batch imports.
  3. Imports are processed. Virtuous processes each import and prepares the data for review.
  4. Your team reviews the import. An admin reviews the imported transactions in Virtuous to confirm everything looks correct.
  5. The import is run. Once reviewed, click Run to finalize the import. This creates the actual Gift records in Virtuous and triggers notifications to any connected subscribers.

For more information, see the Virtuous documentation on the Gift & Contact Importer. 

Contact Matching

This integration automatically matches incoming donations to existing contacts in Virtuous using the donor's reference ID. If a donor does not already exist in Virtuous, a new contact will not be created automatically. Instead, the gift will appear in the importer with a Match Needed status.

To enable automatic contact creation for new donors, turn on Enable Ability to Create New Contacts With No Match on Import in your Virtuous Organization Settings. For more information, see Virtuous: Match Needed, Update Needed, Ready for Import.

Important

Make sure the values mapped to Virtuous Segments and Contacts on your iDonate giving pages match what is already configured in your Virtuous instance. The integration maps incoming donation data to existing records but will not create new ones automatically.