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

# Virtuous Setup Requirements

> Prerequisites and requirements for setting up the WeGive Virtuous integration

# 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 Project ID**
   * At least one project must exist in Virtuous
   * This project will be used for gifts without specific designations
   * Note the Project ID from your Virtuous project settings

3. **Default Communication ID**
   * Required for creating segments (campaigns)
   * Communication ID from existing Virtuous communication record
   * Used for campaign-related segment creation

4. **Account Structure Review**
   * Understand your current contact organization
   * Review existing projects 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
4. **Version Decision**: Choose between V1 and V2 integration (V2 recommended)

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

## Integration Version Selection

### Version 1 (V1) Requirements

**Best For:**

* Simple donor management needs
* Direct one-to-one contact mapping
* Organizations not using household relationships

**Prerequisites:**

* Basic Virtuous setup with contacts
* Standard contact fields populated
* No complex relationship requirements

### Version 2 (V2) Requirements

**Best For:**

* Complex household and family relationships
* Organization and corporate donor management
* Advanced contact individual tracking

**Prerequisites:**

* Understanding of Virtuous Contact → ContactIndividual hierarchy
* Household relationship planning
* Enhanced data structure requirements

**Additional V2 Requirements:**

* 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**
   * Ensure at least one active project exists
   * Review project naming and organization
   * Note project IDs for mapping purposes
   * Understand project categories and designations

3. **Contact Categories**
   * Review individual vs organization contact types
   * Understand any custom contact categories in use
   * Plan for V2 Contact → ContactIndividual relationships if using V2

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 for V2

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**: V2 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

## Version-Specific Considerations

### V1 Setup Considerations

* **Simple Mapping**: Direct contact ID correlation
* **Contact Types**: Individual and Organization contacts
* **Data Structure**: Flat contact relationship model

### V2 Setup Considerations

* **Hierarchical Structure**: Contact → ContactIndividual relationships
* **Household Planning**: Strategy for family/household groupings
* **Primary Individual**: Designation of primary contact individuals
* **Migration Path**: Consider upgrade from V1 if applicable

## Validation Checklist

Before proceeding with setup:

* [ ] Virtuous account has API access enabled
* [ ] API key generated and tested
* [ ] Default project identified and configured
* [ ] Default communication ID obtained
* [ ] Integration version selected (V1 or V2)
* [ ] 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**: No projects exist in Virtuous

* **Solution**: Create at least one project before integration setup
* **Check**: Verify project is active and properly configured

**Issue**: Missing communication ID

* **Solution**: Create a communication record in Virtuous
* **Check**: Note the communication ID for integration setup

**Issue**: Duplicate contact records

* **Solution**: Clean duplicates before initial sync
* **Check**: Use Virtuous's duplicate detection tools

### Version Selection Issues

**Issue**: Unsure which version to choose

* **Solution**: V2 is recommended for new implementations
* **Check**: Consider household management and relationship needs

## Next Steps

Once requirements are met:

1. Proceed to [Version Differences](/virtuous/version-differences)
2. Configure [Integration Settings](/virtuous/configuration-options)
3. Study [Data Mapping](/virtuous/data-mapping/overview) details