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

# Contact Mapping

> Detailed mapping between WeGive donors and Virtuous contacts, including V1 and V2 differences

# Contact Mapping

This document details the comprehensive mapping between WeGive donor records and Virtuous contact objects, covering both V1 and V2 integration versions with their distinct approaches to contact management.

## Overview

Virtuous uses different contact models depending on the integration version:

* **V1**: Direct Contact object mapping with simple one-to-one relationships
* **V2**: Hierarchical Contact → ContactIndividual structure supporting households and organizations

WeGive maps these to the **Donor** object with version-appropriate relationship handling.

## V1 Contact Mapping

### Individual Contact Mapping

#### Core Fields

| WeGive Field   | Virtuous Field | Type   | Required | Transformation                 |
| -------------- | -------------- | ------ | -------- | ------------------------------ |
| `id`           | Correlation ID | String | No       | Stored in WeGive `virtuous_id` |
| `first_name`   | `FirstName`    | String | Yes\*    | Direct mapping                 |
| `middle_name`  | `MiddleName`   | String | No       | Direct mapping                 |
| `last_name`    | `LastName`     | String | Yes\*    | Direct mapping                 |
| `suffix`       | `Suffix`       | String | No       | Direct mapping                 |
| `email_1`      | `EmailAddress` | String | No       | Email validation               |
| `mobile_phone` | `PhoneNumber`  | String | No       | Phone formatting               |

\*Either FirstName or LastName is required in Virtuous

#### Contact Information

**Email Handling:**

* Primary email maps to Virtuous `EmailAddress` field
* Secondary emails can be managed through additional contact methods
* Email validation ensures data quality
* Duplicate email prevention

**Phone Number Management:**

* Mobile phone maps to primary phone number
* Additional phone numbers (home, work) map to secondary contact methods
* Phone number formatting normalized during sync
* International phone number support

**Address Information:**

* Complete address synchronization between systems
* Street address, city, state, postal code mapping
* Country information defaults to organization settings
* Address type designation (home, work, etc.)

### Organization Contact Mapping

#### Core Fields

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

## V2 Enhanced Contact Mapping

### Hierarchical Structure

V2 integration supports Virtuous's advanced contact model:

#### Contact (Household/Organization Level)

* **Purpose**: Represents the household, family unit, or organization
* **Contains**: Multiple ContactIndividual records
* **Address**: Primary household or business address
* **Coordination**: Manages relationships between individuals

#### ContactIndividual (Person Level)

* **Purpose**: Represents specific individuals within the contact
* **Personal Data**: Individual names, emails, phones
* **Relationships**: Role within household or organization
* **Primary Designation**: Identifies main contact person

### V2 Donor to ContactIndividual Mapping

#### Individual Donor Fields

| WeGive Field                             | Virtuous Field | Type    | Required | Transformation              |
| ---------------------------------------- | -------------- | ------- | -------- | --------------------------- |
| `id`                                     | Correlation ID | String  | No       | Multiple correlation fields |
| `first_name`                             | `FirstName`    | String  | Yes      | Direct mapping              |
| `middle_name`                            | `MiddleName`   | String  | No       | Direct mapping              |
| `last_name`                              | `LastName`     | String  | Yes      | Direct mapping              |
| `email_1`                                | `EmailAddress` | String  | No       | Email validation            |
| `mobile_phone`                           | `PhoneNumber`  | String  | No       | Phone formatting            |
| `virtuous_contact_id`                    | `ContactId`    | String  | Yes      | References parent Contact   |
| `virtuous_contact_individual_id`         | `Id`           | String  | Yes      | Individual identifier       |
| `virtuous_is_primary_contact_individual` | `IsPrimary`    | Boolean | No       | Primary designation         |

#### Enhanced Correlation Fields

**V2 Correlation Strategy:**

* `virtuous_contact_id`: Links to the household/organization Contact
* `virtuous_contact_individual_id`: Identifies the specific individual
* `virtuous_is_primary_contact_individual`: Marks the primary contact person
* `virtuous_primary_contact_individual_id`: References primary individual

### Household Management

#### Household to Contact Mapping

| WeGive Field  | Virtuous Field  | Transformation    | Notes                 |
| ------------- | --------------- | ----------------- | --------------------- |
| `id`          | Correlation ID  | Stored mapping    | Household correlation |
| `name`        | `HouseholdName` | Household naming  | Generated or provided |
| `virtuous_id` | `Id`            | Contact reference | Household Contact ID  |

#### Household Relationships

**Family Structure:**

* Spouse relationships automatically coordinated
* Children linked to parent households
* Extended family member connections
* Address sharing within households

**Primary Individual Rules:**

* One primary individual per household
* Primary individual handles main communications
* Gift attribution to primary individual when appropriate
* Automatic primary designation when needed

## Address Mapping

### Address Synchronization

Address information coordinates between both systems with version-specific handling:

#### V1 Address Mapping

* **Direct Mapping**: Individual contact addresses sync directly
* **Address Types**: Home, work, billing address support
* **Organization Addresses**: Business address for organization contacts

#### V2 Address Coordination

* **Household Addresses**: Shared addresses for family members
* **Individual Addresses**: Personal addresses when different from household
* **Address Hierarchy**: Household address inherits to individuals
* **Organization Addresses**: Business addresses for company contacts

### Address Fields

| WeGive Field  | Virtuous Field | Transformation   | Notes                            |
| ------------- | -------------- | ---------------- | -------------------------------- |
| `street_1`    | `Address1`     | Direct mapping   | Primary street address           |
| `street_2`    | `Address2`     | Direct mapping   | Secondary address line           |
| `city`        | `City`         | Direct mapping   | City name                        |
| `state`       | `State`        | Direct mapping   | State/province                   |
| `postal_code` | `PostalCode`   | Direct mapping   | ZIP/postal code                  |
| `country`     | `Country`      | Default handling | Defaults to organization country |

## Data Transformation Rules

### Name Handling

**Individual Name Processing:**

* Name validation ensures required fields are present
* Middle name and suffix handling for complete names
* Name formatting consistency across systems
* Special character handling and normalization

**Organization Name Processing:**

* Business name validation and formatting
* DBA (Doing Business As) name support
* Organization type designation
* Name uniqueness validation

### Contact Information Processing

**Email Management:**

* Email format validation and normalization
* Duplicate email detection and prevention
* Primary email designation
* Email preference coordination

**Phone Number Processing:**

* Phone number formatting and normalization
* International phone number support
* Phone type designation (mobile, home, work)
* Contact preference management

## Sync Operations

### V1 Sync Operations

#### Push Operation (WeGive → Virtuous)

**Create New Contact:**

* Determine contact type (Individual vs Organization)
* Map appropriate fields based on contact type
* Create contact with complete information
* Store correlation ID for future updates

**Update Existing Contact:**

* Use `virtuous_id` for contact identification
* Update changed fields only
* Preserve existing Virtuous-specific data
* Maintain contact type consistency

#### Pull Operation (Virtuous → WeGive)

**Import Contact:**

* Determine contact type from Virtuous data
* Map fields to appropriate WeGive donor structure
* Create or update WeGive donor record
* Store correlation ID for bidirectional sync

### V2 Enhanced Sync Operations

#### Push Operation (WeGive → Virtuous)

**Create New Contact Structure:**

* Determine if Contact (household) exists
* Create Contact if needed for household/organization
* Create ContactIndividual for the person
* Establish relationships and primary designation
* Store multiple correlation IDs

**Household Coordination:**

* Group family members into households
* Coordinate shared information (address, surname)
* Manage primary individual designation
* Handle household-level communications

#### Pull Operation (Virtuous → WeGive)

**Import Contact Hierarchy:**

* Import Contact (household/organization) structure
* Import associated ContactIndividual records
* Create WeGive donors for individuals
* Maintain household relationships
* Preserve primary individual designation

## Matching and Deduplication

### V1 Matching Strategy

**Primary Matching (in order):**

1. **Virtuous ID**: Exact match using stored `virtuous_id`
2. **Email Address**: Match on primary email address
3. **Name Match**: Full name matching for individuals
4. **Organization Name**: Name matching for organizations

### V2 Enhanced Matching

**Hierarchical Matching:**

1. **Contact Individual ID**: Match on `virtuous_contact_individual_id`
2. **Contact ID**: Match on `virtuous_contact_id`
3. **Email Within Household**: Email matching within household context
4. **Name + Household**: Name matching within known households
5. **Create New**: Create new hierarchy when no matches found

### Conflict Resolution

**Update Strategy:**

* **Push Operations**: WeGive data takes precedence
* **Pull Operations**: Virtuous data takes precedence
* **Relationship Coordination**: Preserve existing family relationships

**Field-Level Rules:**

* **Contact Info**: Always update with latest data
* **Names**: Update only if target field is empty
* **Relationships**: Maintain existing household connections
* **Primary Designation**: Coordinate primary individual status

## Validation Rules

### Data Quality Requirements

**V1 Validation:**

* Either first name or last name required for individuals
* Organization name required for organization contacts
* Email format validation when provided
* Phone number format normalization

**V2 Enhanced Validation:**

* ContactIndividual requires name fields
* Contact requires appropriate type designation
* Household relationship validation
* Primary individual designation consistency

### Error Handling

**Common Validation Issues:**

* Missing required name fields
* Invalid email format
* Duplicate contact detection
* Household relationship conflicts

**Automatic Corrections:**

* Name field defaults when missing
* Email format cleaning
* Phone number normalization
* Household relationship resolution

## Performance Optimization

### V1 Performance

* **Simple Operations**: Direct contact mapping
* **Fast Processing**: Minimal relationship overhead
* **Direct Correlation**: Simple ID-based matching

### V2 Performance Considerations

* **Complex Relationships**: Additional processing for households
* **Multiple Lookups**: Contact and ContactIndividual coordination
* **Relationship Management**: Household coordination overhead

### Optimization Strategies

**Batch Processing:**

* Group related operations for efficiency
* Household-aware batching in V2
* Correlation ID caching

**Query Optimization:**

* Index optimization for correlation fields
* Efficient household relationship queries
* Contact hierarchy navigation

## Version Migration

### V1 to V2 Migration

**Migration Process:**

1. **Assessment**: Review existing V1 contact structure
2. **Household Planning**: Plan family groupings
3. **Primary Designation**: Establish primary individual rules
4. **Data Migration**: Convert V1 contacts to V2 hierarchy
5. **Validation**: Verify relationship accuracy

**Data Preservation:**

* All existing contact information maintained
* Relationship data enhanced with household structure
* Historical data remains intact
* Correlation IDs properly migrated

This comprehensive contact mapping documentation ensures accurate donor and contact synchronization between WeGive and Virtuous across both integration versions while maintaining data integrity and supporting complex relationship structures.