> ## Documentation Index
> Fetch the complete documentation index at: https://wegive.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Version Differences: V1 vs V2

> Understanding the differences between Virtuous integration V1 and V2, including migration considerations

# 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.