​

Configuration Options

The WeGive Virtuous integration provides comprehensive configuration options to control data synchronization behavior, version selection, sync frequency, and integration features.

​

Authentication Settings

​

API Configuration

Setting	Type	Required	Description
API Key	String	Yes	Your Virtuous API key for authentication
Enabled	Boolean	Yes	Master toggle to enable/disable the entire integration
Version	String	Yes	Integration version (‘v1’ or ‘v2’) - defaults to ‘v1’

​

API Key Configuration

• Source: Generated from Virtuous Settings → API Keys
• Security: Encrypted and stored securely in WeGive
• Validation: Automatically tested during configuration
• Rotation: Should be rotated periodically for security

​

Version Selection

​

Integration Version

Setting	Options	Default	Description
Version	’v1’, ‘v2'	'v1’	Choose between legacy V1 or enhanced V2 integration

Version Selection Impact:

• V1: Simple contact mapping, direct relationships
• V2: Advanced household support, ContactIndividual hierarchy
• Migration: V1 to V2 migration available
• Recommendation: V2 for new implementations

​

Synchronization Controls

​

Data Type Configuration

Configure what types of data synchronize between platforms:

​

Donors/Contacts Sync

Setting	Default	Description
Push Donors	Enabled	Send WeGive donors to Virtuous as contacts
Pull Donors	Disabled	Import Virtuous contacts to WeGive as donors

V1 Push Donors Configuration:

• Creates individual contacts in Virtuous from WeGive donors
• Updates existing contacts when correlation ID exists
• Handles both individual and organization donor types
• Syncs contact information including addresses and communication details

V2 Push Donors Configuration:

• Creates Contact and ContactIndividual hierarchy in Virtuous
• Manages household relationships and primary individuals
• Enhanced organization contact handling
• Maintains family and relationship structures

​

Transactions/Gifts Sync

Setting	Default	Description
Push Transactions	Enabled	Send WeGive donations to Virtuous as gifts
Pull Transactions	Disabled	Import Virtuous gifts to WeGive

Push Transactions Configuration:

• Sends successful WeGive donations to Virtuous
• Maps payment methods and gift types
• Links gifts to appropriate contacts and projects
• Includes transaction metadata and processing details
• Supports batch processing for efficiency

​

Funds/Projects Sync

Setting	Default	Description
Push Funds	Enabled	Send WeGive funds to Virtuous as projects
Pull Funds	Disabled	Import Virtuous projects to WeGive

​

Campaigns/Segments Sync

Setting	Default	Description
Push Campaigns	Enabled	Send WeGive campaigns to Virtuous as segments
Pull Campaigns	Disabled	Import Virtuous segments to WeGive

​

Recurring Donations Sync

Setting	Default	Description
Push Scheduled Donations	Enabled	Send WeGive recurring plans to Virtuous
Pull Scheduled Donations	Disabled	Import Virtuous recurring gifts to WeGive

​

Advanced Settings

​

Required Configuration

Setting	Type	Required	Description
Default Project ID	String	Yes	Virtuous project ID for gifts without specific designation
Default Communication ID	String	Yes	Virtuous communication ID for creating segments

Important Notes:

• Default Project ID: Must be a valid, active project ID from your Virtuous account
• Default Communication ID: Required for campaign/segment creation functionality
• Used when WeGive transactions or campaigns don’t have specific mappings

​

Sync Behavior Settings

Setting	Options	Default	Description
Real Time	Enabled/Disabled	Disabled	Enable real-time sync via webhooks
Pull By	Field options	’Last Modified Date’	Field to use for pulling data from Virtuous

Real-time Sync:

• Immediate synchronization for critical updates
• Utilizes Virtuous webhooks for instant notifications
• Best for organizations requiring immediate data consistency
• Requires webhook configuration in Virtuous

Scheduled Sync:

• Daily batch processing for bulk operations
• More efficient for large data volumes
• Reduces API usage and rate limit concerns
• Default sync method for most organizations

​

Data Flow Configuration

​

Sync Direction Matrix

Data Type	Push (WeGive → Virtuous)	Pull (Virtuous → WeGive)	Bidirectional
Donors/Contacts	Configurable	Configurable	Supported
Transactions/Gifts	Configurable	Configurable	Supported
Funds/Projects	Configurable	Configurable	Supported
Campaigns/Segments	Configurable	Configurable	Supported
Recurring Donations	Configurable	Configurable	Supported

​

Conflict Resolution

When the same record exists in both systems: For Push Operations (WeGive → Virtuous):

• WeGive data takes precedence
• Virtuous records are updated with WeGive values
• Correlation IDs prevent duplicate creation

For Pull Operations (Virtuous → WeGive):

• Virtuous data takes precedence
• WeGive records are updated with Virtuous values
• Existing relationships are preserved

​

Version-Specific Configuration

​

V1 Configuration Options

Contact Management:

• Simple contact mapping rules
• Direct correlation ID management
• Individual and organization contact types
• Standard field mapping configuration

​

V2 Configuration Options

Enhanced Contact Management:

• Household relationship rules
• Primary individual designation logic
• ContactIndividual management settings
• Enhanced organization handling options

Additional V2 Settings:

• Contact hierarchy management
• Family relationship coordination
• Primary contact individual rules
• Household address coordination

​

Integration Features

​

Data Processing Options

Setting	Options	Default	Description
Batch Processing	Enabled/Disabled	Enabled	Process transactions in batches for efficiency
Error Handling	Standard/Enhanced	Standard	Level of error handling and retry logic
Data Validation	Basic/Comprehensive	Basic	Extent of data validation before sync

​

Monitoring and Logging

Setting	Options	Default	Description
Log Level	Minimal/Standard/Detailed	Standard	Amount of detail in integration logs
Performance Tracking	Enabled/Disabled	Enabled	Track sync performance and timing
Error Notifications	Dashboard/Email/Both	Dashboard	How to receive error notifications

​

Organization-Specific Settings

​

Custom Field Mapping

Organizations can configure custom field mappings between WeGive and Virtuous:

• Field Pairing: Map specific WeGive fields to corresponding Virtuous fields
• Data Type Matching: Ensure compatible data types between systems
• Validation Rules: Custom fields follow the same validation as standard fields
• Version Compatibility: Field mapping rules vary between V1 and V2

​

Data Filters

Filter Type	Description	Example
Date Range	Limit sync to specific date ranges	Last 12 months
Amount Threshold	Only sync transactions above certain amount	$25 minimum
Contact Type	Filter by individual vs organization	Individual only
Project Categories	Restrict which projects synchronize	Operating funds only

​

API Configuration

​

Rate Limiting

Setting	Behavior	Description
API Requests	Virtuous limits	Respects Virtuous API rate limiting
Batch Optimization	Automatic	Uses batch endpoints when available
Retry Logic	Built-in	Automatic retry with exponential backoff

​

Performance Settings

Setting	Default	Range	Description
Batch Size	100	25-500	Records processed per batch operation
Concurrent Operations	3	1-5	Number of simultaneous API operations
Timeout Settings	30 seconds	10-60 seconds	API request timeout duration

​

Recommended Configuration Approaches

​

Standard Configuration (Most Organizations)

Purpose: Send WeGive data to Virtuous while maintaining Virtuous as the authoritative source Settings:

• Enable push for donors, transactions, funds, and campaigns
• Disable pull operations initially
• Use V2 for new implementations
• Enable batch processing for efficiency
• Configure real-time sync for critical updates

Best For: Organizations that want to enrich their Virtuous data with WeGive activity

​

Bidirectional Configuration (Advanced Users)

Purpose: Keep both systems completely synchronized Settings:

• Enable both push and pull for all data types
• Use V2 for enhanced relationship management
• Enable real-time sync for immediate updates
• Configure comprehensive error handling
• Monitor performance closely

Best For: Organizations that actively use both platforms and need complete data synchronization

​

Migration Configuration (V1 to V2 Upgrade)

Purpose: Safely migrate from V1 to V2 integration Settings:

• Plan household relationship strategy
• Configure primary individual designation rules
• Enable enhanced V2 features gradually
• Maintain data validation during transition
• Monitor migration progress carefully

Best For: Existing V1 customers upgrading to V2 capabilities

​

Configuration Best Practices

​

Initial Setup

1. Choose Appropriate Version: V2 recommended for new implementations
2. Test Thoroughly: Use test connection before enabling sync
3. Start Conservative: Begin with push-only configuration
4. Monitor Closely: Watch logs during first 24-48 hours
5. Validate Data: Verify accuracy of synced records

​

Ongoing Management

1. Regular Reviews: Check configuration monthly
2. Performance Monitoring: Track sync times and success rates
3. Error Analysis: Review and resolve integration errors promptly
4. Version Evaluation: Consider V2 upgrade if using V1
5. Settings Optimization: Adjust configuration based on usage patterns

​

Security Considerations

1. API Key Rotation: Update API keys quarterly
2. Access Control: Limit who can modify integration settings
3. Audit Logging: Maintain records of configuration changes
4. Data Privacy: Ensure compliance with data protection regulations

​

Troubleshooting Configuration Issues

​

Common Problems

Issue: Sync operations failing

• Check: Verify all required settings are configured
• Verify: Test API connection is successful
• Review: Ensure default project and communication IDs are valid

Issue: Duplicate records being created

• Check: Correlation ID mapping is working correctly
• Verify: Email matching is functioning properly
• Review: Sync direction settings are appropriate

Issue: Version-specific problems

• V1: Check simple contact mapping rules
• V2: Verify household relationship configuration
• Migration: Review V1 to V2 transition settings

Issue: Performance problems

• Check: Batch size settings are optimal
• Verify: Rate limiting is not being exceeded
• Review: Real-time vs batch sync configuration

​

Configuration Validation

Required Fields Check:

• API key is valid and has proper permissions
• Default project ID exists and is active
• Default communication ID is valid
• Version selection is appropriate for needs

Data Quality Verification:

• Field mappings are configured correctly
• Custom field rules are properly defined
• Filter settings match organizational needs
• Error handling is appropriately configured

This comprehensive configuration guide ensures optimal setup and ongoing management of your WeGive Virtuous integration, whether using V1 or V2 architecture.