​

Version Differences: V1 vs V2

The WeGive Virtuous integration supports two distinct versions to accommodate different organizational needs and data structures. Understanding these differences is crucial for choosing the right version and planning your integration strategy.

​

Overview of Versions

​

Version 1 (V1) - Legacy

V1 provides a straightforward, direct mapping approach between WeGive donors and Virtuous contacts. It’s designed for organizations with simple donor management needs.

​

Version 2 (V2) - Current

V2 supports Virtuous’s advanced Contact → ContactIndividual hierarchy, enabling sophisticated household and relationship management. It’s the recommended version for new implementations.

​

Core Architecture Differences

​

Data Structure Mapping

​

V1 Data Structure

Simple Contact Model:

• One WeGive donor = One Virtuous contact
• Direct virtuous_id field on donors table
• Single contact per donor record
• Flat relationship structure

Contact Types:

• Individual contacts for people
• Organization contacts for companies
• No household or family relationships

​

V2 Data Structure

Hierarchical Contact Model:

• WeGive donors can map to Contact → ContactIndividual structure
• Multiple tracking fields:
  • virtuous_contact_id - References the Virtuous Contact (household/organization)
  • virtuous_contact_individual_id - References specific ContactIndividual
  • virtuous_is_primary_contact_individual - Marks primary individual
• Support for household relationships
• Enhanced organization handling

Contact Hierarchy:

• Contact: Represents household, family, or organization
• ContactIndividual: Specific people within the contact
• Primary Individual: Designated main contact person

​

Feature Comparison

​

Donor Management

Feature	V1 Implementation	V2 Implementation
Individual Donors	Direct contact mapping	ContactIndividual within Contact
Organization Donors	Organization contact	Enhanced company handling
Household Relationships	Not supported	Full household support
Family Members	Separate contacts	Linked ContactIndividuals
Primary Contact	Not applicable	Primary individual designation
Address Management	Simple address sync	Household address coordination

​

Sync Operations

​

V1 Sync Behavior

Push Donors (WeGive → Virtuous):

• Creates individual contact for each donor
• Updates existing contact using virtuous_id
• Simple field mapping
• No relationship handling

Pull Donors (Virtuous → WeGive):

• Imports contacts as individual donors
• Direct field mapping
• Creates separate donor for each contact

​

V2 Sync Behavior

Push Donors (WeGive → Virtuous):

• Creates Contact structure for households
• Creates ContactIndividual for each person
• Maintains family/household relationships
• Designates primary contact individuals
• Enhanced organization contact handling

Pull Donors (Virtuous → WeGive):

• Imports Contact hierarchy
• Creates WeGive donors for ContactIndividuals
• Maintains household relationships
• Preserves primary individual designation

​

Data Fields and Tracking

​

V1 Fields

Donor Table Fields:

• virtuous_id - Single Virtuous contact ID

Household Table Fields:

• Basic household information only

​

V2 Fields

Donor Table Fields:

• virtuous_contact_id - References Virtuous Contact
• virtuous_contact_individual_id - References ContactIndividual
• virtuous_is_primary_contact_individual - Boolean flag
• virtuous_primary_contact_individual_id - Primary individual reference

Household Table Fields:

• virtuous_id - Virtuous Contact ID for household

​

Use Case Scenarios

​

When to Use V1

Ideal For:

• Simple donor management needs
• Organizations not using household relationships
• Direct one-to-one contact mapping requirements
• Legacy systems requiring minimal complexity

Scenarios:

• Small nonprofits with individual donors only
• Organizations with simple contact structures
• Existing V1 implementations that meet current needs
• Systems where household relationships aren’t important

​

When to Use V2

Ideal For:

• Complex household and family relationships
• Organizations with significant corporate donors
• Advanced contact individual tracking needs
• Modern CRM usage patterns

Scenarios:

• Organizations managing family foundations
• Nonprofits with household giving patterns
• Complex corporate relationship management
• Advanced donor relationship tracking requirements

​

Migration Considerations

​

Migrating from V1 to V2

Migration Process:

1. Data Assessment: Review current V1 data structure
2. Relationship Planning: Plan household groupings
3. Primary Individual Strategy: Determine primary contact designation
4. Migration Execution: Convert existing relationships to V2 structure
5. Validation: Verify data integrity post-migration

Data Transformation:

• Existing virtuous_id values are migrated to appropriate V2 fields
• Individual contacts may be grouped into household structures
• Primary individual designations are established
• Relationship hierarchies are created

​

Migration Benefits

Enhanced Functionality:

• Access to household relationship management
• Improved organization contact handling
• Better alignment with Virtuous best practices
• Enhanced data structure for complex relationships

Preserved Data:

• All existing donor relationships maintained
• Historical transaction data preserved
• Contact information retained
• Integration logs and audit trails continued

​

Configuration Differences

​

V1 Configuration

Settings:

• Simple integration version flag
• Basic field mapping configuration
• Standard sync direction controls
• Direct contact correlation settings

​

V2 Configuration

Enhanced Settings:

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

​

Performance Implications

​

V1 Performance

Characteristics:

• Faster sync operations (simpler structure)
• Lower API call volume
• Direct field mapping reduces complexity
• Minimal relationship processing

​

V2 Performance

Characteristics:

• More comprehensive sync operations
• Additional API calls for relationship management
• Enhanced data validation and processing
• Household coordination overhead

Optimization:

• Batch processing for efficiency
• Intelligent relationship grouping
• Optimized primary individual handling
• Performance monitoring and tuning

​

API Differences

​

V1 API Usage

Endpoints:

• Standard Contact endpoints
• Direct field mapping
• Simple CRUD operations
• Individual contact management

​

V2 API Usage

Enhanced Endpoints:

• Contact and ContactIndividual endpoints
• Relationship management APIs
• Household coordination calls
• Primary individual designation APIs

​

Best Practices by Version

​

V1 Best Practices

• Keep It Simple: Maintain direct contact relationships
• Data Quality: Focus on individual contact accuracy
• Sync Efficiency: Leverage direct mapping for speed
• Migration Planning: Consider V2 upgrade path

​

V2 Best Practices

• Relationship Strategy: Plan household groupings carefully
• Primary Individual Management: Establish clear designation rules
• Data Coordination: Ensure household data consistency
• Performance Monitoring: Track complex sync operations

​

Decision Framework

​

Choose V1 If:

• Simple donor management requirements
• No household relationship needs
• Performance is critical priority
• Existing V1 implementation meets needs
• Minimal technical complexity desired

​

Choose V2 If:

• Household and family relationships are important
• Complex organization donor management needed
• Modern CRM usage patterns required
• Future-proofing integration architecture
• Advanced donor relationship tracking desired

​

Future Considerations

​

V1 Support

• Current Status: Fully supported for existing customers
• New Implementations: V2 recommended instead
• Migration Path: Available to upgrade to V2
• Long-term: Continued support with encouragement to migrate

​

V2 Development

• Current Status: Recommended for all new implementations
• Active Development: Ongoing feature enhancements
• Feature Pipeline: Additional relationship management features
• Integration: Enhanced Virtuous API utilization

​

Technical Implementation Notes

​

V1 Implementation

• Simpler codebase and logic
• Direct field mapping algorithms
• Standard sync operation patterns
• Minimal relationship processing

​

V2 Implementation

• Enhanced relationship management logic
• Sophisticated household coordination
• Advanced primary individual handling
• Complex data validation and processing

This understanding of version differences will help you choose the right integration approach and plan for optimal donor relationship management within your organization’s WeGive Virtuous integration.