​

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

​

Recommended Setup

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