​

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
• Gift Mapping
• Project Mapping
• Segment Mapping
• RecurringGift Mapping

​

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.