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

# Person Mapping

> Detailed mapping between WeGive donors and Planning Center person records with contact information

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