> ## 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 Data Mapping Overview

> Comprehensive mapping between Virtuous CRM objects and WeGive donor platform data structures

# Data Mapping Overview

This document provides a comprehensive overview of how the WeGive donor platform maps to Virtuous CRM objects, including differences between V1 and V2 integration versions and their relationships with WeGive API endpoints.

## Object Mapping Categories

The Virtuous integration maps objects across two main categories with version-specific differences:

1. **Virtuous CRM Objects**
   * Core contact and donor management
   * Gift and transaction tracking
   * Project and fund management
   * Segment and campaign management
   * Recurring gift tracking

2. **WeGive Platform Objects**
   * Donor engagement platform
   * Payment processing system
   * Campaign and fundraising tools
   * Recurring donation management

## Core Object Mappings

### Contact/Donor Management

#### V1 Integration Mapping

| Virtuous Object | Type         | WeGive Object        | API Endpoint      | Sync Direction |
| --------------- | ------------ | -------------------- | ----------------- | -------------- |
| Contact         | Individual   | Donor (Individual)   | `/donors/{donor}` | Bidirectional  |
| Contact         | Organization | Donor (Organization) | `/donors/{donor}` | Bidirectional  |

#### V2 Integration Mapping

| Virtuous Object   | Type                   | WeGive Object          | API Endpoint              | Sync Direction |
| ----------------- | ---------------------- | ---------------------- | ------------------------- | -------------- |
| Contact           | Household/Organization | Household/Organization | `/households/{household}` | Bidirectional  |
| ContactIndividual | Individual             | Donor (Individual)     | `/donors/{donor}`         | Bidirectional  |

### Transaction Management

| Virtuous Object | Type           | WeGive Object | API Endpoint                  | Sync Direction |
| --------------- | -------------- | ------------- | ----------------------------- | -------------- |
| Gift            | Donation       | Transaction   | `/transactions/{transaction}` | Bidirectional  |
| Gift            | Pledge Payment | Transaction   | `/transactions/{transaction}` | Bidirectional  |
| Gift            | Recurring      | Transaction   | `/transactions/{transaction}` | Bidirectional  |

### Fund Management

| Virtuous Object | Type          | WeGive Object | API Endpoint    | Sync Direction |
| --------------- | ------------- | ------------- | --------------- | -------------- |
| Project         | Fund Category | Fund          | `/funds/{fund}` | Bidirectional  |

### Campaign Management

| Virtuous Object | Type           | WeGive Object | API Endpoint            | Sync Direction |
| --------------- | -------------- | ------------- | ----------------------- | -------------- |
| Segment         | Campaign Group | Campaign      | `/campaigns/{campaign}` | Bidirectional  |

### Recurring Donation Management

| Virtuous Object | Type           | WeGive Object      | API Endpoint                | Sync Direction |
| --------------- | -------------- | ------------------ | --------------------------- | -------------- |
| RecurringGift   | Recurring Plan | Scheduled Donation | `/scheduled-donations/{id}` | Bidirectional  |

## Virtuous Object Details

### V1 Contact Object

The Contact object in V1 represents both individual donors and organizations with direct mapping:

#### Individual Contact Fields

* **Basic Information**: First name, middle name, last name, suffix
* **Contact Details**: Primary email, phone numbers (home, work, mobile)
* **Address Information**: Complete mailing and billing addresses
* **Identification**: Unique Virtuous contact ID for tracking
* **Contact Type**: Individual designation

#### Organization Contact Fields

* **Organization Name**: Full legal or business name
* **Contact Information**: Primary business email and phone
* **Address Information**: Primary business address
* **Identification**: Unique Virtuous contact ID for tracking
* **Contact Type**: Organization designation

### V2 Contact Structure

The V2 integration uses Virtuous's hierarchical contact model:

#### Contact (Household/Organization)

* **Household Information**: Family name, household details
* **Organization Information**: Company name, business details
* **Primary Address**: Main household or business address
* **Contact Coordination**: Manages multiple individuals

#### ContactIndividual (Person)

* **Personal Information**: First name, middle name, last name, suffix
* **Individual Contact**: Personal email, direct phone numbers
* **Relationship Role**: Role within household or organization
* **Primary Designation**: Whether this is the primary contact individual

### Gift Object

The Gift object represents all financial interactions:

* **Financial Details**: Gift amount, date, and payment method
* **Contact Link**: Connection to the contact who made the gift
* **Project Designation**: Which project(s) the gift supports
* **Gift Type**: Donation, pledge payment, recurring gift, etc.
* **Processing Information**: Transaction fees and reference numbers
* **Recognition**: Gift acknowledgment and recognition details

### Project Object

The Project object represents funding categories and designations:

* **Project Information**: Name, description, and current status
* **Financial Goals**: Target amounts and progress tracking
* **Category Classification**: Type of project (fund, campaign, etc.)
* **Organization**: Display order and management settings

### Segment Object

The Segment object represents donor groups and campaigns:

* **Group Definition**: Criteria for segment membership
* **Communication Settings**: Associated communication preferences
* **Campaign Link**: Connection to fundraising campaigns
* **Dynamic Updates**: Automatic segment membership updates

### RecurringGift Object

The RecurringGift object manages recurring donation schedules:

* **Schedule Information**: Frequency, amount, and timing
* **Payment Details**: Payment method and processing information
* **Contact Association**: Link to the donor making recurring gifts
* **Project Designation**: Default project for recurring gifts
* **Status Tracking**: Active, paused, or cancelled status

## Version-Specific Mapping Differences

### V1 Donor Mapping

#### Individual Donor to Contact

| WeGive Field   | Virtuous Field           | Transformation       | Required |
| -------------- | ------------------------ | -------------------- | -------- |
| `id`           | Stored as correlation ID | -                    | No       |
| `first_name`   | `FirstName`              | Direct mapping       | Yes      |
| `middle_name`  | `MiddleName`             | Direct mapping       | No       |
| `last_name`    | `LastName`               | Direct mapping       | Yes      |
| `email_1`      | `EmailAddress`           | Email validation     | No       |
| `mobile_phone` | `PhoneNumber`            | Phone formatting     | No       |
| `virtuous_id`  | `Id`                     | Correlation tracking | No       |

#### Organization Donor to Contact

| WeGive Field  | Virtuous Field           | Transformation       | Required |
| ------------- | ------------------------ | -------------------- | -------- |
| `id`          | Stored as correlation ID | -                    | No       |
| `name`        | `Name`                   | Direct mapping       | Yes      |
| `email_1`     | `EmailAddress`           | Email validation     | No       |
| `virtuous_id` | `Id`                     | Correlation tracking | No       |

### V2 Enhanced Mapping

#### Donor to ContactIndividual

| WeGive Field                             | Virtuous Field           | Transformation    | Required |
| ---------------------------------------- | ------------------------ | ----------------- | -------- |
| `id`                                     | Stored as correlation ID | -                 | No       |
| `first_name`                             | `FirstName`              | Direct mapping    | Yes      |
| `middle_name`                            | `MiddleName`             | Direct mapping    | No       |
| `last_name`                              | `LastName`               | Direct mapping    | Yes      |
| `email_1`                                | `EmailAddress`           | Email validation  | No       |
| `mobile_phone`                           | `PhoneNumber`            | Phone formatting  | No       |
| `virtuous_contact_id`                    | `ContactId`              | Contact reference | Yes      |
| `virtuous_contact_individual_id`         | `Id`                     | Individual ID     | Yes      |
| `virtuous_is_primary_contact_individual` | `IsPrimary`              | Boolean flag      | No       |

#### Household to Contact

| WeGive Field  | Virtuous Field           | Transformation      | Required |
| ------------- | ------------------------ | ------------------- | -------- |
| `id`          | Stored as correlation ID | -                   | No       |
| `name`        | `HouseholdName`          | Household naming    | No       |
| `virtuous_id` | `Id`                     | Contact correlation | Yes      |

## Transaction Object Mapping

### WeGive Transaction to Virtuous Gift

| WeGive Field    | Virtuous Field           | Transformation              | Required |
| --------------- | ------------------------ | --------------------------- | -------- |
| `id`            | Stored as correlation ID | -                           | No       |
| `amount`        | `Amount`                 | Cents to dollars conversion | Yes      |
| `created_at`    | `GiftDate`               | Date formatting             | Yes      |
| `owner` (donor) | `ContactId`              | Contact reference           | Yes      |
| `fund`          | `ProjectId`              | Project mapping             | Yes      |
| `source_type`   | `GiftType`               | Payment method mapping      | No       |
| `status`        | `GiftStatus`             | Status mapping              | No       |

#### Payment Method Mapping

| WeGive Source Type | Virtuous Gift Type | Description                |
| ------------------ | ------------------ | -------------------------- |
| `card`             | `CreditCard`       | Credit/debit card payments |
| `bank`             | `ACH`              | Electronic fund transfers  |
| `check`            | `Check`            | Check payments             |
| `cash`             | `Cash`             | Cash donations             |
| `stock`            | `Stock`            | Securities donations       |
| `other`            | `Other`            | Other payment methods      |

## Fund/Project Mapping

### WeGive Fund to Virtuous Project

| WeGive Field  | Virtuous Field           | Transformation      | Required |
| ------------- | ------------------------ | ------------------- | -------- |
| `id`          | Stored as correlation ID | -                   | No       |
| `name`        | `Name`                   | Direct mapping      | Yes      |
| `description` | `Description`            | Direct mapping      | No       |
| `virtuous_id` | `Id`                     | Project correlation | No       |

## Campaign/Segment Mapping

### WeGive Campaign to Virtuous Segment

| WeGive Field  | Virtuous Field           | Transformation      | Required |
| ------------- | ------------------------ | ------------------- | -------- |
| `id`          | Stored as correlation ID | -                   | No       |
| `name`        | `Name`                   | Direct mapping      | Yes      |
| `description` | `Description`            | Direct mapping      | No       |
| `virtuous_id` | `Id`                     | Segment correlation | No       |

## Data Synchronization Rules

### Correlation ID Management

**V1 Correlation:**

* Single `virtuous_id` field tracks Virtuous contact ID
* Direct one-to-one mapping between donors and contacts
* Simple correlation logic for matching

**V2 Enhanced Correlation:**

* Multiple correlation fields for hierarchical structure
* `virtuous_contact_id` for household/organization reference
* `virtuous_contact_individual_id` for specific individual
* Primary individual designation tracking

### Matching Logic

1. **Exact ID Match**: Use correlation IDs when available
2. **Email Matching**: For contacts without correlation IDs
3. **Name + Address**: Fallback for organizations and households
4. **Create New**: When no match found

### Sync Direction Rules

#### Push Operations (WeGive → Virtuous)

* **New Records**: Create new Virtuous records
* **Existing Records**: Update based on correlation ID
* **Data Precedence**: WeGive data overwrites Virtuous data
* **Required Fields**: Ensure all Virtuous required fields are populated

#### Pull Operations (Virtuous → WeGive)

* **New Records**: Create new WeGive records
* **Existing Records**: Update based on correlation ID
* **Data Precedence**: Virtuous data overwrites WeGive data
* **Field Mapping**: Transform Virtuous format to WeGive format

### Conflict Resolution

**Duplicate Prevention:**

* Email address uniqueness for individual contacts
* Organization name uniqueness for organization contacts
* Household coordination for V2 implementations

**Update Strategy:**

* **Last Modified Wins**: Most recent update takes precedence
* **Field-Level Merging**: Specific field update rules
* **Manual Review**: Flag conflicts for administrative review

## API Endpoint Reference

### WeGive API Endpoints

#### Donor Management

* `GET /donors` - List all donors
* `GET /donors/{donor}` - Get specific donor
* `POST /donors` - Create new donor
* `PUT /donors/{donor}` - Update existing donor

#### Transaction Management

* `GET /transactions` - List all transactions
* `GET /transactions/{transaction}` - Get specific transaction
* `POST /transactions` - Create new transaction

#### Fund Management

* `GET /funds` - List all funds
* `GET /funds/{fund}` - Get specific fund
* `POST /funds` - Create new fund

#### Campaign Management

* `GET /campaigns` - List all campaigns
* `GET /campaigns/{campaign}` - Get specific campaign

### Virtuous API Endpoints

#### V1 Contact Management

* `GET /Contact` - List all contacts
* `GET /Contact/{id}` - Get specific contact
* `POST /Contact` - Create new contact
* `PUT /Contact/{id}` - Update existing contact

#### V2 Enhanced Contact Management

* `GET /Contact` - List all contacts (households/organizations)
* `GET /Contact/{id}/Individual` - Get contact individuals
* `POST /Contact` - Create new contact
* `POST /Contact/{id}/Individual` - Create contact individual

#### Gift Management

* `GET /Gift` - List all gifts
* `POST /Gift` - Create new gift
* `POST /v2/Gift/Transactions` - Batch gift creation

#### Project Management

* `GET /Project` - List all projects
* `POST /Project` - Create new project

#### Segment Management

* `GET /Segment` - List all segments
* `POST /Segment` - Create new segment

## Integration Notes

### Data Validation

**Required Field Validation:**

* Virtuous requires at least first name OR last name for individuals
* Organizations require name field
* Gifts require amount, date, and contact reference
* Projects require name and active status

**Format Requirements:**

* Phone numbers: Flexible formatting, normalized during sync
* Email addresses: Must be valid email format
* Dates: ISO 8601 format for API calls
* Amounts: Decimal format with 2 decimal places

### Performance Considerations

**Batch Processing:**

* V2 supports enhanced batch endpoints
* Transaction batching for efficiency
* Rate limiting respectful API usage

**Version-Specific Performance:**

* V1: Simpler operations, faster processing
* V2: More complex but comprehensive relationship management

## Related Documentation

* [Contact Mapping](./contact)
* [Gift Mapping](./gift)
* [Project Mapping](./project)
* [Segment Mapping](./segment)
* [RecurringGift Mapping](./recurring-gift)

## Future Enhancements

Features under development:

* **Enhanced Custom Fields**: Organization-specific field mapping
* **Advanced Relationships**: Extended family and business relationships
* **Communication Preferences**: Integrated communication management
* **Event Integration**: Event registration and participation data

This comprehensive data mapping ensures accurate bidirectional synchronization between WeGive and Virtuous while supporting both V1 and V2 integration architectures.