​

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.