Virtuous

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:

1. In the Donately dashboard, go to Integrations and click Install on the Virtuous card.
2. Enter the email address and password you use to sign in to Virtuous CRM.
3. 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.
4. On success, you are returned to the Integrations page and the Virtuous card shows Active.

Configuration

Per-account settings live on the Virtuous card's Configure page in the Donately dashboard (/native-integrations/virtuous/configure). Three sections are configurable today:

Pre-installed Custom Fields

Donately's default field mappings rely on a small set of Gift custom fields existing in Virtuous so each gift can carry the Donately donation, transaction, subscription, campaign, fundraiser, and form identifiers alongside the standard amount/date/donor data. These fields are normally created once at integration installation time — either by the Donately team during onboarding or by your Virtuous admin from the list below.

If you need to (re)create them by hand, add each one in Virtuous under Setup → Custom Fields → Gift as type Text:

You only need the fields you want surfaced on the gift in Virtuous — any field you skip will be omitted from gift payloads. dntly_donation_id is the one strict requirement, since gift matching uses it to avoid creating duplicate gifts on every resync.

Field Mapping

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

Constituent

Gift

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

Gift Matching

Advanced

Project Linking

Each Virtuous gift can be designated to a Project — Virtuous's accounting object for funds, programs, or campaigns. Donately picks the Project for each gift by walking an ordered list of rules. Rules are evaluated top-to-bottom, and the first matching rule wins. A donation that doesn't match any rule will not be designated to a Project unless you add a fallback rule.

Each rule has a type and the fields specific to that type:

Order rules from most specific to least specific. If you use a fallback_project rule, put it last so it only fires when nothing earlier matched.

Example settings.project_rules:

[
  { "type": "form", "match_value": "frm_abc123", "virtuous_project_id": 12345 },
  { "type": "meta_data", "meta_key": "appeal", "match_value": "endofyear", "virtuous_project_id": 67890 },
  { "type": "campaign", "match_value": "cmp_xyz789", "virtuous_project_id": 11111 },
  { "type": "fallback_project", "virtuous_project_id": 99999 }
]

The matched rule's virtuous_project_id is sent on the gift payload as projects: [{ projectId, amountDesignated }] with amountDesignated equal to the full gift amount (multi-project splits are not yet supported).

Missing Name Fallback

Virtuous's contact API requires both firstName and lastName on every constituent — a create or update with either field blank is rejected with a 400. Donately, however, accepts donors with no name (anonymous donors, single-field donation forms, mobile flows that only ask for email). Without a fallback strategy those donors and their gifts would be silently dropped on every sync attempt.

Two strategies are available, configured via settings.missing_name_fallback:

Either way, if the donor has no name and no usable email (blank, or no @), the integration falls back to recording the skip — there's nothing to synthesize from.

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