​

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 Communication ID
   • Required before any WeGive campaign can push to Virtuous — pushing a campaign without this set fails outright
   • Communication ID from an existing Virtuous communication record
   • Virtuous campaigns are called “Segments”; WeGive creates one per WeGive campaign, tied to this communication ID
3. Account Structure Review
   • Understand your current contact organization
   • Review existing projects (Virtuous’s term for what WeGive calls funds) 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

​

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

​

Contact Model Requirements

The integration uses Virtuous’s hierarchical Contact → ContactIndividual model. Prerequisites:

• Understanding of the Virtuous Contact → ContactIndividual hierarchy
• Household relationship planning
• 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
   • Existing projects in Virtuous aren’t a prerequisite — WeGive creates a new Virtuous Project automatically the first time a fund needs to push
   • Review project naming and organization if you want the auto-created ones to align with an existing convention
   • Note project IDs for mapping purposes if you’re pre-linking funds manually
3. Contact Categories
   • Review individual vs organization contact types
   • Understand any custom contact categories in use
   • Plan for Contact → ContactIndividual relationships
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
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: The Contact → ContactIndividual model 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

​

Setup Considerations

• Hierarchical Structure: Contact → ContactIndividual relationships
• Household Planning: Strategy for family/household groupings
• Primary Individual: Designation of primary contact individuals

​

Validation Checklist

Before proceeding with setup:

• Virtuous account has API access enabled
• API key generated and tested
• Default communication ID obtained
• 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: Missing communication ID

• Solution: Create a communication record in Virtuous
• Check: Note the communication ID for integration setup — required before any campaign push will succeed

Issue: Duplicate contact records

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

​

Next Steps

Once requirements are met:

1. Configure Integration Settings
2. Study Data Mapping details