Planning Center API Integration

Integration Summary

Church Management Platform provides a fully integrated, two-way API connection with Planning Center Online (PCO), a widely-used church management platform. This integration synchronizes people, families, and groups between both systems, ensuring data stays consistent regardless of where changes originate.

What Gets Synced

PCO API Overview

Planning Center Online exposes a REST API conforming to the JSON:API 1.0 specification. Each PCO product module has its own versioned API endpoint. The API supports sideloading related resources (?include=), field-level filtering (?where[field]=value), ordering, and cursor-based pagination (max 100 per page).

Key Query Features

• Sideloading: ?include=emails,phone_numbers — fetch related resources in a single request.
• Filtering: ?where[first_name]=John or ?where[updated_at][gte]=... for incremental sync.
• Search: ?where[search_name_or_email_or_phone_number]=... — combined search.
• Ordering: ?order=last_name or ?order=-created_at (descending).
• Pagination: ?per_page=100 (max 100). Follow links.next URL for next page.

Base URLs

Authentication

The integration uses Personal Access Tokens (PAT) for server-to-server authentication via HTTP Basic Auth. Credentials are configured per-church in appsettings.json under the PlanningCenter section.

• Auth method: HTTP Basic Auth with AppId:Secret
• Token type: Personal Access Token (never expires until revoked)
• Scope: Full read/write access to the organization's PCO data
• Configuration: PlanningCenter:AppId and PlanningCenter:Secret in appsettings

OAuth 2.0 is also supported by PCO for multi-tenant SaaS deployments (access tokens expire after 2 hours with long-lived refresh tokens). The current single-church integration uses PAT for simplicity.

Write Capabilities Matrix

PCO's API is heavily read-biased. The People module is fully writable, Groups support membership writes only, and Check-Ins/Calendar are entirely read-only.

Read Capabilities Matrix

All PCO modules provide comprehensive read access. The integration uses read endpoints for inbound sync, data comparison, and admin-facing read-only views.

All Endpoints Used

Complete list of PCO API endpoints consumed by the Church Management Platform integration.

People Module (Read/Write)

Groups Module (Read + Membership Write)

Check-Ins Module (Read-Only)

Calendar Module (Read-Only)

Inbound Sync (Pull from PCO)

Inbound sync pulls data from Planning Center into the local database. The sync service (PcoSyncService) supports four sync types that can be triggered individually or as a full sync.

Sync Types

Matching Logic

When pulling people from PCO, the sync service uses a three-tier matching strategy:

1. pco_id match — if a local person already has a pco_id matching the PCO record, update in place.
2. Email match — if no pco_id match, search local person_emails for a matching email address.
3. Name + DOB match — if no email match, compare first_name + last_name + date of birth as a fallback.
4. Create new — if no match found, create a new local person record with the PCO data.

Data Ownership

• PCO authoritative for: demographics (first_name, last_name, gender, dob), contact info (emails, phones, addresses)
• Local authoritative for: operational data (allergies, photo_url, is_verified, group memberships, check-in records)

Outbound Push (Local → PCO)

Outbound push sends locally-created or modified records to Planning Center. The push service supports four push types.

Push Types

Real-Time Webhooks

PCO pushes real-time change notifications via webhooks, reducing the need for polling. Church Management Platform receives and processes these events at POST /api/pco/webhook.

Supported Webhook Events

Security

• Webhook payloads are verified via X-PCO-Webhooks-Authenticity header using HMAC-SHA256
• Webhook secret is configured in PlanningCenter:WebhookSecret
• PCO retries up to 16 times with exponential backoff over 5+ days on delivery failure

Read-Only Data Endpoints

The admin UI exposes several read-only views of PCO data for comparison and verification purposes.

Entity Mapping

How Church Management Platform entities map to Planning Center equivalents. The pco_id column on local tables stores the corresponding PCO record ID for bidirectional lookup.

Model Differences

Key structural differences between Church Management Platform and Planning Center data models.

Families / Households

• PCO HouseholdMembership has no relationship role (no Parent/Child/Spouse). Child status comes from Person's child boolean.
• PCO addresses are on Person (not Household). Our system stores addresses on families.
• Our authorized_pickup_ids and relationships table have no PCO equivalent.

Groups

• Our 3-level hierarchy (Department → Area → Group) is richer than PCO's flat GroupType → Group structure.
• PCO membership role is only "leader" or "member" — no Coach/Other from our small_group_leader_type.
• Our small group metadata (meeting day, frequency, area, childcare) has no PCO equivalent. PCO stores schedule as freetext.

Check-Ins

• PCO uses a Station model (physical iPads) vs. our software-based kiosk.
• PCO resolves children to rooms via Location age/grade filters. Our system uses hierarchical group-based event resolution.
• Check-ins performed in Church Management Platform cannot be pushed to PCO (API limitation).

Rate Limits & Performance

PCO enforces 100 requests per minute per organization. The integration uses several strategies to work within this constraint.

Rate Limit Mitigation

• SemaphoreSlim rate limiter in PcoApiClient — throttles at 90 req/min to stay safely under the 100/min limit
• Sideloading — ?include=emails,phone_numbers fetches contacts in one request instead of per-person calls
• IAsyncEnumerable pagination — streams results page-by-page without loading all data into memory
• Incremental sync — ?where[updated_at][gte]=... pulls only records changed since last sync
• Webhooks — real-time person change notifications eliminate polling for People module

Bulk Operation Timing

Admin UI

The integration is managed through the PCO Sync page at /admin/pco-sync, accessible to ADMIN users via the sidebar and dashboard.

Features

• Connection status — shows whether PCO credentials are configured, with "Test Connection" button
• Sync actions — buttons for People, Families, Groups, and Full Sync (inbound pull)
• Push actions — buttons for People, Families, Group Memberships, and Full Push (outbound)
• Live progress — running sync/push shows real-time created/updated/skipped counters (polled every 3 seconds)
• Sync history — table of last 20 runs with type, status badge, timing, and record counts
• Webhook config — shows webhook URL, secret status, and subscription count

Configuration

All PCO integration settings are in appsettings.json under the PlanningCenter section. Each church deployment configures its own PCO credentials — no code changes required.

// appsettings.json
{
  "PlanningCenter": {
    "AppId": "",          // PCO Personal Access Token App ID
    "Secret": "",         // PCO Personal Access Token Secret
    "WebhookSecret": ""  // HMAC-SHA256 secret for webhook verification
  }
}

Database Schema Support

• pco_id TEXT column on people, families, locations, events, church_group (with partial unique indexes)
• pco_sync_log table tracks all sync/push runs (type, status, timing, record counts, error messages)
• PCO webhook controller at POST /api/pco/webhook (HMAC-SHA256 verified, no authentication required)

Backend Components