​

Data Mapping Overview

This document provides a comprehensive overview of how the WeGive donor platform maps to Planning Center modules, specifically focusing on the People and Giving modules and their relationships with WeGive API endpoints.

​

Object Mapping Categories

The Planning Center integration maps objects across two main Planning Center modules:

1. People Module

   • Contact and person management
   • Communication information tracking
   • Address and family relationships
   • Contact notes and interaction history

2. Giving Module

   • Donation and gift tracking
   • Fund and designation management
   • Batch processing and organization
   • Payment source and method tracking
   • Recurring gift management

​

Core Object Mappings

​

People Module Mapping

Planning Center Object	WeGive Object	API Endpoint	Sync Direction
Person	Donor (Individual)	/donors/{donor}	Bidirectional
Email	Email (embedded)	Embedded in donor	Bidirectional
PhoneNumber	Phone (embedded)	Embedded in donor	Bidirectional
Address	Address (embedded)	Embedded in donor	Bidirectional

​

Giving Module Mapping

Planning Center Object	WeGive Object	API Endpoint	Sync Direction
Donation	Transaction	/transactions/{transaction}	Bidirectional
Batch	Daily Batch Group	Internal grouping	Push Only
Fund	Fund	/funds/{fund}	Bidirectional
PaymentSource	Payment Method	Embedded in transaction	Push Only
Designation	Fund Allocation	/fund_allocations/{allocation}	Bidirectional
RecurringGift	Scheduled Donation	/scheduled-donations/{id}	Bidirectional

​

Planning Center Object Details

​

People Module Objects

​

Person Object

The Person object represents individual contacts with comprehensive information:

Core Person Fields:

• Basic Information: First name, middle name, last name, suffix
• Demographics: Birthdate, anniversary, gender
• Contact Details: Primary email and phone number references
• Address Information: Primary address reference
• Family Relationships: Household and family member connections
• Identification: Unique Planning Center person ID

​

Email Object

Email addresses linked to person records:

Email Fields:

• Email Address: The actual email address
• Location: Type designation (home, work, other)
• Primary: Boolean flag for primary email
• Person Link: Reference to associated person

​

PhoneNumber Object

Phone numbers associated with person records:

Phone Number Fields:

• Number: The phone number in various formats
• Location: Type designation (mobile, home, work, fax)
• Primary: Boolean flag for primary phone
• Person Link: Reference to associated person

​

Address Object

Physical addresses for person records:

Address Fields:

• Street Address: Complete street address
• City: City name
• State: State or province
• Zip Code: Postal code
• Location: Type designation (home, work, other)
• Primary: Boolean flag for primary address
• Person Link: Reference to associated person

​

Giving Module Objects

​

Donation Object

Individual gift records with complete transaction information:

Donation Fields:

• Amount: Gift amount in cents
• Created At: Date and time of donation
• Person: Reference to donor person record
• Payment Source: Reference to payment method
• Batch: Reference to donation batch
• Designations: Fund allocation details

​

Batch Object

Organized groups of donations for accounting purposes:

Batch Fields:

• Description: Batch description (e.g., “WeGive Import - 2024-01-15”)
• Committed At: When batch was finalized
• Total Cents: Total amount of all donations in batch
• Donations Count: Number of donations in batch
• Status: Batch processing status

​

Fund Object

Giving categories and designation options:

Fund Fields:

• Name: Fund name and description
• Visibility: Whether fund is visible to donors
• Default: Whether this is the default fund
• Created At: Fund creation date
• Updated At: Last modification date

​

PaymentSource Object

Payment method information for tracking:

Payment Source Fields:

• Name: Payment source name (always “WeGive” for WeGive transactions)
• Description: Additional payment source details

​

Designation Object

Fund allocation details for gifts:

Designation Fields:

• Amount: Amount designated to specific fund
• Donation: Reference to parent donation
• Fund: Reference to designated fund

​

RecurringGift Object

Scheduled donation arrangements:

Recurring Gift Fields:

• Amount: Recurring gift amount
• Schedule: Frequency and timing information
• Person: Reference to donor person record
• Payment Source: Default payment method
• Status: Active, paused, or cancelled status

​

WeGive Object Mappings

​

Donor Object Mapping

​

WeGive Donor to Planning Center Person

WeGive Field	Planning Center Field	Transformation	Required
id	Correlation ID	Stored mapping	No
first_name	first_name	Direct mapping	Yes
middle_name	middle_name	Direct mapping	No
last_name	last_name	Direct mapping	Yes
email_1	Email.address	Email object creation	No
mobile_phone	PhoneNumber.number	Phone object creation	No
planning_center_id	id	Person ID correlation	No

​

Contact Information Mapping

Email Address Handling:

• Primary email creates Email object linked to Person
• Secondary emails create additional Email objects
• Email location type defaults to “home”
• Primary flag set on first email address

Phone Number Processing:

• Mobile phone creates PhoneNumber object with location “mobile”
• Additional phone numbers create separate PhoneNumber objects
• Phone type determined by field name (mobile, home, work)
• Primary flag set on first phone number

Address Information:

• Complete address creates Address object linked to Person
• Address location type defaults to “home”
• Geographic data mapped to appropriate fields
• Primary flag set on address

​

Transaction Object Mapping

​

WeGive Transaction to Planning Center Donation

WeGive Field	Planning Center Field	Transformation	Required
id	Correlation ID	Stored mapping	No
amount	amount_cents	Direct cents mapping	Yes
created_at	created_at	Date formatting	Yes
owner (donor)	person	Person reference	Yes
fund	Designation.fund	Fund reference	Yes
planning_center_id	id	Donation ID correlation	No

​

Batch Processing

Daily Batch Creation:

• Transactions grouped by date into daily batches
• Batch description format: “WeGive Import - [YYYY-MM-DD]”
• All transactions for a day included in single batch
• Batch automatically committed after successful processing

Payment Source Assignment:

• All WeGive transactions use “WeGive” payment source
• Payment source created automatically if missing
• Original payment method preserved in transaction metadata
• Unified payment source simplifies Planning Center management

​

Fund Object Mapping

​

WeGive Fund to Planning Center Fund

WeGive Field	Planning Center Field	Transformation	Required
id	Correlation ID	Stored mapping	No
name	name	Direct mapping	Yes
description	description	Direct mapping	No
is_active	visibility	Visibility mapping	No
planning_center_id	id	Fund ID correlation	No

​

Fund Designation Mapping

Single Fund Designation:

• WeGive transaction with single fund creates one Designation
• Designation amount equals transaction amount
• Fund reference links to Planning Center fund

Multiple Fund Allocations:

• WeGive fund allocations create multiple Designations
• Each allocation creates separate Designation object
• Designation amounts sum to transaction total
• All designations linked to same donation

​

Scheduled Donation Mapping

​

WeGive Scheduled Donation to Planning Center RecurringGift

WeGive Field	Planning Center Field	Transformation	Required
id	Correlation ID	Stored mapping	No
amount	amount_cents	Direct cents mapping	Yes
frequency	Schedule configuration	Frequency mapping	Yes
donor	person	Person reference	Yes
fund	Default fund reference	Fund assignment	No
planning_center_id	id	RecurringGift correlation	No

​

Data Synchronization Rules

​

Correlation ID Management

Primary Correlation:

• planning_center_id field stores Planning Center object ID
• Direct ID matching for existing records
• Correlation prevents duplicate creation
• Bidirectional reference maintenance

Matching Logic:

1. Exact ID Match: Use stored planning_center_id when available
2. Email Matching: For persons without correlation ID
3. Name Matching: Full name comparison for individuals
4. Create New: When no match found

​

Sync Direction Rules

​

Push Operations (WeGive → Planning Center)

• New Records: Create new Planning Center objects
• Existing Records: Update based on correlation ID
• Data Precedence: WeGive data overwrites Planning Center data
• Batch Organization: Transactions organized into daily batches

​

Pull Operations (Planning Center → WeGive)

• New Records: Create new WeGive objects
• Existing Records: Update based on correlation ID
• Data Precedence: Planning Center data overwrites WeGive data
• Relationship Preservation: Maintain existing contact relationships

​

Conflict Resolution

Duplicate Prevention:

• Email address uniqueness for person records
• Planning Center ID correlation prevents duplicates
• Batch processing prevents transaction duplication

Update Strategy:

• Last Modified Wins: Most recent update takes precedence
• Field-Level Merging: Specific field update rules
• Relationship Maintenance: Preserve family and household connections

​

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

​

Planning Center API Endpoints

​

People Module

• GET /people/v2/people - List all people
• GET /people/v2/people/{id} - Get specific person
• POST /people/v2/people - Create new person
• PATCH /people/v2/people/{id} - Update existing person
• GET /people/v2/emails - List email addresses
• GET /people/v2/phone_numbers - List phone numbers
• GET /people/v2/addresses - List addresses

​

Giving Module

• GET /giving/v2/donations - List all donations
• POST /giving/v2/donations - Create new donation
• GET /giving/v2/batches - List all batches
• POST /giving/v2/batches - Create new batch
• GET /giving/v2/funds - List all funds
• POST /giving/v2/funds - Create new fund
• GET /giving/v2/recurring_gifts - List recurring gifts

​

Integration Notes

​

Data Validation

Required Field Validation:

• Planning Center requires first name OR last name for persons
• Donations require amount, person reference, and batch assignment
• Funds require name and visibility setting
• Email addresses must pass format validation

Format Requirements:

• Phone numbers: Flexible formatting accepted
• Email addresses: Must be valid email format
• Dates: ISO 8601 format for API calls
• Amounts: Integer values in cents

​

Performance Considerations

Batch Processing:

• Daily batches optimize API usage
• Bulk operations reduce API call volume
• Rate limiting compliance (70 requests per 20 seconds)
• Background job processing for large operations

API Optimization:

• Incremental sync for efficiency
• Correlation ID caching
• Request batching where possible
• Smart retry logic for failed requests

​

Related Documentation

• Person Mapping
• Donation Mapping
• Fund Mapping
• Batch Processing

​

Future Enhancements

Features under consideration:

• Advanced Contact Relationships: Extended family and household management
• Custom Fields: Organization-specific field mapping
• Communication Preferences: Integrated communication management
• Event Integration: Planning Center Services integration for event-based giving

This comprehensive data mapping ensures accurate bidirectional synchronization between WeGive and Planning Center while maintaining data integrity and supporting efficient church management workflows.