​
Setup Requirements

Before configuring the WeGive Virtuous integration, ensure you meet all the necessary prerequisites and have access to the required resources.

​
Prerequisites

​
Virtuous Account Requirements

  • Active Subscription: Valid Virtuous CRM subscription
  • API Access: Virtuous account with API access enabled
  • Administrator Privileges: Admin-level access to generate API keys
  • Minimum Version: Compatible with current Virtuous API version

​
WeGive Account Requirements

  • Organization Admin: Administrator privileges in your WeGive organization
  • Integration Access: Access to the WeGive integrations dashboard
  • Billing Status: Active WeGive subscription with integration features enabled

​
Required Information

​
From Virtuous

Gather the following information from your Virtuous account:

  1. API Key

    • Generated from Virtuous Settings → API Keys
    • Keep this secure - it provides full access to your Virtuous data

  2. Default Project ID

    • At least one project must exist in Virtuous
    • This project will be used for gifts without specific designations
    • Note the Project ID from your Virtuous project settings

  3. Default Communication ID

    • Required for creating segments (campaigns)
    • Communication ID from existing Virtuous communication record
    • Used for campaign-related segment creation

  4. Account Structure Review

    • Understand your current contact organization
    • Review existing projects and segments
    • Identify any custom fields in use

​
From WeGive

Ensure you have:

  1. Organization ID: Your WeGive organization identifier
  2. Admin Access: Ability to configure integrations
  3. Data Review: Understanding of existing donor and transaction data
  4. Version Decision: Choose between V1 and V2 integration (V2 recommended)

​
API Access Setup

​
Generating Virtuous API Key

  1. Login to Virtuous

    • Access your Virtuous CRM dashboard
    • Ensure you have administrator privileges

  2. Navigate to API Settings

    • Go to Settings → API Keys
    • If API access is not visible, contact Virtuous support

  3. Generate New Key

    • Click Create New API Key
    • Provide a descriptive name (e.g., “WeGive Integration”)
    • Copy the generated key immediately
    • Store securely - this key won’t be shown again

  4. Test API Access

    • Verify the key works by making a test API call
    • Ensure proper permissions are assigned

​
API Permissions

Your API key must have access to:

  • Contacts: Read and write access for donor management
  • Gifts: Read and write access for donation processing
  • Projects: Read and write access for fund management
  • Segments: Read and write access for campaign management
  • RecurringGifts: Read and write access for recurring donation management

​
Integration Version Selection

​
Version 1 (V1) Requirements

Best For:

  • Simple donor management needs
  • Direct one-to-one contact mapping
  • Organizations not using household relationships

Prerequisites:

  • Basic Virtuous setup with contacts
  • Standard contact fields populated
  • No complex relationship requirements

​
Version 2 (V2) Requirements

Best For:

  • Complex household and family relationships
  • Organization and corporate donor management
  • Advanced contact individual tracking

Prerequisites:

  • Understanding of Virtuous Contact → ContactIndividual hierarchy
  • Household relationship planning
  • Enhanced data structure requirements

Additional V2 Requirements:

  • Primary contact individual designation strategy
  • Household grouping methodology
  • Organization contact management plan

​
Data Preparation

​
Virtuous Data Review

Before integration setup:

  1. Clean Existing Data

    • Remove duplicate contact records
    • Standardize naming conventions
    • Verify contact information accuracy
    • Ensure proper contact types (Individual vs Organization)

  2. Project Structure

    • Ensure at least one active project exists
    • Review project naming and organization
    • Note project IDs for mapping purposes
    • Understand project categories and designations

  3. Contact Categories

    • Review individual vs organization contact types
    • Understand any custom contact categories in use
    • Plan for V2 Contact → ContactIndividual relationships if using V2

  4. Communication Setup

    • Ensure at least one communication record exists
    • Note communication ID for segment creation
    • Review existing segments and their purposes

​
WeGive Data Review

  1. Donor Records

    • Review existing donor profiles
    • Identify potential duplicates with Virtuous
    • Prepare for initial matching process
    • Understand household relationships for V2

  2. Transaction History

    • Review donation records that need syncing
    • Understand fund/designation mappings
    • Plan for historical data import if needed

  3. Fund Alignment

    • Compare WeGive funds with Virtuous projects
    • Plan project mapping strategy
    • Identify any new projects needed

  4. Campaign Planning

    • Review existing WeGive campaigns
    • Plan Virtuous segment mapping
    • Understand communication requirements

​
Network and Security

​
Firewall Configuration

Ensure your network allows:

  • Outbound HTTPS: Port 443 to api.virtuoussoftware.com
  • API Endpoints: Access to Virtuous API endpoints
  • Webhook Support: Inbound HTTPS for real-time sync (optional)

​
Security Considerations

  1. API Key Storage

    • Store API keys securely
    • Rotate keys periodically
    • Monitor API usage for unexpected activity

  2. Data Privacy

    • Ensure compliance with data protection regulations
    • Review data sharing agreements
    • Understand data residency requirements

  3. Access Control

    • Limit integration access to necessary personnel
    • Use role-based permissions
    • Maintain audit logs of configuration changes

​
Testing Environment

  1. Virtuous Sandbox

    • Use Virtuous test environment if available
    • Create test data for integration validation

  2. WeGive Test Mode

    • Utilize WeGive’s test connection feature
    • Validate configuration before going live

  3. Data Backup

    • Export current data from both systems
    • Maintain backups before initial sync
    • Document rollback procedures

​
Technical Specifications

​
API Rate Limits

  • Standard Limits: Virtuous API rate limiting applies
  • Batch Processing: Optimized batch endpoints for efficiency
  • Real-time Sync: Webhook support for immediate updates
  • Retry Logic: Automatic backoff and retry handling

​
Data Volume Considerations

  • Large Datasets: Plan for longer initial sync times
  • Contact Hierarchy: V2 requires additional processing for relationships
  • Concurrent Operations: Understand API concurrency limits
  • Batch Processing: Leverage batch endpoints for efficiency

​
Integration Frequency

  • Real-time Sync: For critical updates via webhooks
  • Daily Batches: For bulk transaction processing
  • Manual Triggers: For testing and recovery

​
Version-Specific Considerations

​
V1 Setup Considerations

  • Simple Mapping: Direct contact ID correlation
  • Contact Types: Individual and Organization contacts
  • Data Structure: Flat contact relationship model

​
V2 Setup Considerations

  • Hierarchical Structure: Contact → ContactIndividual relationships
  • Household Planning: Strategy for family/household groupings
  • Primary Individual: Designation of primary contact individuals
  • Migration Path: Consider upgrade from V1 if applicable

​
Validation Checklist

Before proceeding with setup:

  • Virtuous account has API access enabled
  • API key generated and tested
  • Default project identified and configured
  • Default communication ID obtained
  • Integration version selected (V1 or V2)
  • WeGive admin access confirmed
  • Network connectivity verified
  • Data backup completed
  • Security policies reviewed
  • Testing strategy planned

​
Common Issues

​
API Access Problems

Issue: Cannot generate API key

  • Solution: Contact Virtuous support to enable API access
  • Check: Verify account subscription includes API features

Issue: API key authentication fails

  • Solution: Regenerate API key and verify proper copying
  • Check: Ensure no extra spaces or characters in key

​
Data Preparation Issues

Issue: No projects exist in Virtuous

  • Solution: Create at least one project before integration setup
  • Check: Verify project is active and properly configured

Issue: Missing communication ID

  • Solution: Create a communication record in Virtuous
  • Check: Note the communication ID for integration setup

Issue: Duplicate contact records

  • Solution: Clean duplicates before initial sync
  • Check: Use Virtuous’s duplicate detection tools

​
Version Selection Issues

Issue: Unsure which version to choose

  • Solution: V2 is recommended for new implementations
  • Check: Consider household management and relationship needs

​
Next Steps

Once requirements are met:

  1. Proceed to Version Differences
  2. Configure Integration Settings
  3. Study Data Mapping details