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

# Planning Center Data Mapping Overview

> Comprehensive mapping between Planning Center modules and WeGive donor platform data structures

# 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](./person)
* [Donation Mapping](./donation)
* [Fund Mapping](./fund)
* [Batch Processing](./batch)

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