Virtuous Integration — Donately Docs

Overview

The Virtuous integration syncs Donately donor and donation data to Virtuous CRM Constituents and Gifts. It supports custom field mapping and recurring gift tracking.

Once connected, syncs are triggered automatically each time a donation is created, updated, or refunded in Donately.

What Gets Synced

Constituent — Donor identity, address, and contact information
Gift — Each donation, including recurring subscription details

Connecting

Virtuous does not offer a standard OAuth authorization screen. Instead, it uses password-based authentication (OAuth 2.0 Resource Owner Password Credentials) to exchange your Virtuous username and password for an access token, which Donately stores and uses for all subsequent syncs.

To connect Virtuous to Donately:

In the Donately dashboard, go to Integrations and click Install on the Virtuous card.
Enter the email address and password you use to sign in to Virtuous CRM.
If your Virtuous account has multi-factor authentication enabled, you will be prompted for a one-time code after submitting your credentials. Enter the code Virtuous sends to your authenticator app or email and click Connect again.
On success, you are returned to the Integrations page and the Virtuous card shows Active.

Credentials are never stored. Donately forwards your Virtuous email and password to the Virtuous token endpoint and discards them as soon as the access token is received. Only the access token is persisted.

Configuration

Per-account settings live on the Virtuous card's Configure page in the Donately dashboard (/native-integrations/virtuous/configure). Today the only configurable setting is Custom Field Mapping.

Gift Defaults Coming Soon

Planned settings for future releases — not yet configurable from the dashboard:

Setting	Description
default_fund_id	Virtuous fund or GL code applied to gifts when no specific designation is provided
default_gift_type	Gift type written to all gifts (e.g., `Cash`, `Credit Card`, `Online`)
default_donor_type	Constituent type applied to new constituents (e.g., `Individual`, `Organization`)

Field Mapping

Default mappings from Donately fields to Virtuous properties. These can be overridden using custom field mapping.

Constituent

Donately Field	Virtuous Field
unique_identifier	dntly_donor_id (custom)
email	email
first_name	first_name
last_name	last_name
phone_number	phone
street_address	address.street
street_address_2	address.street2
city	address.city
state	address.state
zip_code	address.postal_code
country	address.country

Gift

Donately Field	Virtuous Field
unique_identifier	dntly_donation_id (custom)
donation_name	description
donation_amount	amount
donation_date	date
currency	currency
anonymous	is_anonymous
on_behalf_of	tribute.name
comment	comment
transaction_id	dntly_transaction_id (custom)
processor	dntly_processor (custom)
donation_type	dntly_donation_type (custom)
status	dntly_status (custom)
subscription_frequency	dntly_subscription_frequency (custom)
subscription_id	dntly_subscription_id (custom)
campaign_title	dntly_campaign (custom)
fundraiser_title	dntly_fundraiser (custom)
form_id	dntly_form_id (custom)

Record Matching

The integration uses the following strategies to find existing records before creating new ones. Strategies are tried in order — the first match wins.

Constituent Matching

Strategy	Description
FindByPersonId	Primary match using the Donately donor ID stored in the `dntly_donor_id` custom field
FindByEmail	Fallback match by donor email address

Gift Matching

Strategy	Description
FindByDonationId	Match by Donately donation ID stored in the `dntly_donation_id` custom field

Advanced

Custom Field Mapping

You can override the default field mappings with a custom mapping. Custom mappings are defined as a JSON object where keys are Donately field names and values are the target Virtuous property names.

{
  "Person": {
    "email": "email",
    "unique_identifier": "dntly_donor_id",
    "phone_number": "phone"
  },
  "Donation": {
    "donation_amount": "amount",
    "unique_identifier": "dntly_donation_id"
  }
}

Person — Maps donor fields to Virtuous Constituent properties
Donation — Maps donation fields to Virtuous Gift properties

Custom mappings are merged with the defaults. You only need to specify the fields you want to override — any fields not listed in your custom mapping will use the default mapping.