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

# Configuration Options

> Detailed configuration settings and options for the WeGive Virtuous integration

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