​

Person Mapping

This document details the comprehensive mapping between WeGive donor records and Planning Center person objects, including associated contact information such as emails, phone numbers, and addresses.

​

Overview

Planning Center’s People module uses a structured approach to contact management with the Person object as the central record and separate objects for Email, PhoneNumber, and Address information. WeGive maps these to the Donor object with embedded contact information.

​

Core Person Mapping

​

Primary Fields

WeGive Field	Planning Center Field	Type	Required	Transformation
id	Correlation ID	String	No	Stored in WeGive planning_center_id
first_name	first_name	String	Yes*	Direct mapping
middle_name	middle_name	String	No	Direct mapping
last_name	last_name	String	Yes*	Direct mapping
suffix	suffix	String	No	Direct mapping
planning_center_id	id	String	No	Person ID correlation

*Either first_name or last_name is required in Planning Center

​

Extended Fields

WeGive Field	Planning Center Field	Transformation	Notes
birthdate	birthdate	Date format	Optional demographic data
anniversary	anniversary	Date format	Optional anniversary date
gender	gender	Direct mapping	Optional demographic field
created_at	created_at	ISO 8601 format	Record creation timestamp
updated_at	updated_at	ISO 8601 format	Last modification timestamp

​

Contact Information Mapping

​

Email Address Management

Planning Center stores email addresses as separate Email objects linked to Person records:

​

Email Object Structure

WeGive Field	Planning Center Field	Transformation	Notes
email_1	Email.address	Direct mapping	Primary email address
email_2	Email.address	Additional Email object	Secondary email address
-	Email.location	Default “home”	Email type designation
-	Email.primary	Boolean flag	Primary email designation

​

Email Processing Rules

Primary Email Handling:

• WeGive email_1 creates primary Email object
• Email location defaults to “home”
• Primary flag set to true for first email
• Email validation ensures proper format

Secondary Email Processing:

• WeGive email_2 creates additional Email object
• Secondary emails marked as non-primary
• Email location can be “work”, “other”, or “home”
• Multiple secondary emails supported

Email Validation:

• Email format validation before sync
• Duplicate email detection within organization
• Invalid emails logged but don’t prevent person creation
• Email uniqueness maintained across Planning Center

​

Phone Number Management

Phone numbers stored as separate PhoneNumber objects:

​

PhoneNumber Object Structure

WeGive Field	Planning Center Field	Transformation	Notes
mobile_phone	PhoneNumber.number	Direct mapping	Mobile phone number
home_phone	PhoneNumber.number	Additional PhoneNumber object	Home phone number
work_phone	PhoneNumber.number	Additional PhoneNumber object	Work phone number
-	PhoneNumber.location	Phone type mapping	Phone category
-	PhoneNumber.primary	Boolean flag	Primary phone designation

​

Phone Type Mapping

WeGive Field	Planning Center Location	Primary Flag
mobile_phone	”mobile”	true
home_phone	”home”	false
work_phone	”work”	false

​

Phone Number Processing

Phone Number Formatting:

• Flexible input format acceptance
• Normalization during sync process
• International phone number support
• Extension handling where applicable

Phone Type Assignment:

• Mobile phone designated as primary contact
• Home and work phones as secondary contacts
• Phone type determines Planning Center location field
• Contact preference coordination

​

Address Management

Address information stored as separate Address objects:

​

Address Object Structure

WeGive Field	Planning Center Field	Transformation	Notes
street_1	Address.street	Direct mapping	Primary street address
street_2	Address.street	Combined with street_1	Secondary address line
city	Address.city	Direct mapping	City name
state	Address.state	Direct mapping	State/province
postal_code	Address.zip	Direct mapping	ZIP/postal code
country	Address.country	Direct mapping	Country code
-	Address.location	Default “home”	Address type
-	Address.primary	Boolean flag	Primary address designation

​

Address Processing Rules

Address Combination:

• WeGive street_1 and street_2 combined into single Planning Center street field
• Address formatting normalized for consistency
• Geographic data validation where possible
• International address support with proper country codes

Address Type Management:

• Primary address designated as “home” location
• Address type affects communication preferences
• Multiple addresses supported per person
• Address hierarchy maintained

​

Data Transformation

​

Person Creation Processing

WeGive to Planning Center Person:

• Validate required name fields (first_name OR last_name)
• Create Person object with basic information
• Create associated Email objects for each email address
• Create PhoneNumber objects for each phone number
• Create Address object for mailing address
• Store correlation ID for future updates

Planning Center to WeGive Donor:

• Import Person basic information
• Retrieve and map primary Email to email_1
• Retrieve and map primary PhoneNumber to mobile_phone
• Retrieve and map primary Address to mailing address
• Store Planning Center person ID for correlation

​

Contact Information Coordination

Email Coordination:

• Primary email becomes WeGive email_1
• Additional emails mapped to email_2 or stored separately
• Email preferences coordinated between systems
• Email validation and cleanup during sync

Phone Coordination:

• Primary phone (usually mobile) becomes WeGive mobile_phone
• Home phone mapped to home_phone field
• Work phone mapped to work_phone field
• Phone type preservation for proper categorization

Address Coordination:

• Primary address becomes WeGive mailing address
• Address formatting normalized for display
• Geographic data preserved for location services
• Address type and preference settings maintained

​

Sync Operations

​

Push Operation (WeGive → Planning Center)

​

Create New Person

Process:

1. Validate required fields (name information)
2. Create Person object with basic information
3. Create Email objects for each email address
4. Create PhoneNumber objects for each phone number
5. Create Address object for address information
6. Store Person ID in WeGive planning_center_id field

​

Update Existing Person

Process:

1. Use planning_center_id for person identification
2. Update Person object fields if changed
3. Update, create, or delete Email objects as needed
4. Update, create, or delete PhoneNumber objects as needed
5. Update Address object if address changed
6. Maintain relationship integrity

​

Pull Operation (Planning Center → WeGive)

​

Import Person

Process:

1. Retrieve Person object with basic information
2. Retrieve associated Email objects and map to WeGive fields
3. Retrieve PhoneNumber objects and map to appropriate fields
4. Retrieve Address objects and map to mailing address
5. Create or update WeGive donor record
6. Store Person ID for correlation

​

Contact Information Import

Email Import:

• Primary email mapped to email_1
• Secondary emails mapped to email_2 or additional fields
• Email preferences imported where applicable

Phone Import:

• Mobile phone mapped to mobile_phone
• Home phone mapped to home_phone
• Work phone mapped to work_phone
• Phone preferences and types preserved

Address Import:

• Primary address mapped to mailing address
• Address type and preference settings imported
• Geographic data preserved for location services

​

Matching and Deduplication

​

Person Matching Strategy

Primary Matching (in order):

1. Planning Center ID: Exact match using stored planning_center_id
2. Email Address: Match on primary email address
3. Full Name: First name and last name combination
4. Partial Name: Last name and phone number combination
5. Create New: When no reliable match found

​

Duplicate Prevention

Email-Based Matching:

• Primary email address uniqueness within organization
• Case-insensitive email matching
• Email domain validation for organizational addresses
• Duplicate email prevention across person records

Name-Based Matching:

• Full name comparison with normalization
• Nickname and abbreviation handling
• Middle name consideration in matching
• Suffix and title handling

​

Conflict Resolution

Update Strategy:

• Push Operations: WeGive data takes precedence
• Pull Operations: Planning Center data takes precedence
• Contact Information: Most recent update wins
• Relationship Preservation: Maintain family connections

Field-Level Rules:

• Basic Information: Update when source field is more complete
• Contact Details: Always update with latest information
• Demographic Data: Update only if target field is empty
• Timestamps: Preserve creation date, update modification date

​

Validation Rules

​

Required Field Validation

Planning Center Requirements:

• Either first_name OR last_name must be provided
• Person object creation requires at least one name field
• Email addresses must pass format validation
• Phone numbers must contain sufficient digits

Data Quality Checks:

• Name field completeness validation
• Email format and domain validation
• Phone number format and length validation
• Address completeness for geographic data

​

Error Handling

Validation Errors:

• Missing required name fields
• Invalid email address format
• Malformed phone numbers
• Incomplete address information

Error Recovery:

• Name field defaults when missing (e.g., “Unknown” for missing last name)
• Email format correction attempts
• Phone number formatting normalization
• Address field completion from partial data

​

Performance Optimization

​

Contact Information Efficiency

Batch Contact Processing:

• Group person creation with contact information
• Minimize API calls through efficient batching
• Contact information created with person in single operation
• Relationship maintenance during bulk operations

Query Optimization:

• Efficient person lookup using correlation IDs
• Contact information retrieval optimization
• Index utilization for person matching
• Caching of frequently accessed contact data

​

API Usage Optimization

Request Minimization:

• Combined person and contact information requests
• Efficient use of include parameters for related data
• Batch updates for multiple contact information changes
• Incremental sync for changed contact information only

​

Integration with Family Relationships

​

Household Coordination

Family Member Relationships:

• Person records maintain individual identity
• Family relationships preserved in Planning Center structure
• Household addresses coordinated across family members
• Contact preferences managed at individual level

Address Sharing:

• Family members can share household addresses
• Individual addresses maintained when different
• Address updates coordinated across family members
• Primary address designation for households

​

Communication Preferences

Contact Preference Coordination:

• Individual communication preferences respected
• Household-level communication coordination
• Email and phone preference management
• Opt-out and unsubscribe handling

This comprehensive person mapping ensures accurate contact information synchronization between WeGive and Planning Center while maintaining data integrity and supporting effective communication management.