Planning Center API Reference

API Overview

Planning Center Online (PCO) exposes a REST API conforming to the JSON:API 1.0 specification. Each PCO product has its own versioned API endpoint.

Base URLs

JSON:API 1.0 Request/Response Format

All responses follow JSON:API structure with data, included (sideloaded relationships), links (pagination), and meta sections.

// GET response (single resource)
{
  "data": {
    "type": "Person",
    "id": "12345",
    "attributes": {
      "first_name": "John",
      "last_name": "Smith",
      "remote_id": 42        // your system's ID stored on PCO
    },
    "relationships": { ... }
  },
  "included": [ ... ],     // sideloaded via ?include=emails,phone_numbers
  "links": { "next": "..." } // cursor-based pagination
}

// POST/PATCH request body
{
  "data": {
    "type": "Person",
    "attributes": {
      "first_name": "John",
      "last_name": "Smith"
    }
  }
}

Key Query Features

• Sideloading: ?include=emails,phone_numbers — fetch related resources in a single request.
• Filtering: ?where[first_name]=John — field-level filtering.
• 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.

Authentication

PCO offers two authentication methods. Both produce the same API access.

Option 1: Personal Access Token (PAT)

Best for single-org server-to-server integration. No user interaction required after initial setup.

• Created at api.planningcenteronline.com/oauth/applications
• Uses HTTP Basic Auth: application_id:secret
• Full read/write access to that org's data
• Never expires (until revoked)

# Example: List all people with PAT
curl -u "app_id:secret" \
  https://api.planningcenteronline.com/people/v2/people?per_page=100

Option 2: OAuth 2.0

Best for multi-org apps where each church authorizes access independently.

• Authorization: api.planningcenteronline.com/oauth/authorize
• Token exchange: api.planningcenteronline.com/oauth/token
• Access tokens expire after 2 hours
• Refresh tokens are long-lived
• Scopes: people, check_ins, groups, calendar, services, giving

Write Capabilities Matrix

This is the most important constraint for integration planning. PCO's API is heavily read-biased — most resources are read-only.

People API Read/Write

The People API is the most complete for integration. Full CRUD on people, emails, phones, addresses, and households.

Person Endpoints

Writable Person Attributes

first_name, last_name, given_name, nickname, middle_name, birthdate (YYYY-MM-DD), gender, child (boolean), grade, graduation_year, medical_notes, status, membership, avatar, remote_id (integer — store your system's people.id here)

Contact Endpoints (scoped to person)

Household Endpoints

Household writable attributes: name, primary_contact_id, avatar.

Groups API Partial Write

Groups and group types are read-only. Only memberships can be created and updated via the API.

Read-Only Endpoints

Group attributes (read-only): name, description, enrollment_open, enrollment_strategy, memberships_count, schedule (freetext), header_image, location_type_preference.

Writable: Memberships

Membership writable: person_id (write-only), role ("leader" or "member" only), joined_at.

Check-Ins API Read-Only

The entire Check-Ins API is read-only. Check-in records are created through the PCO Check-Ins iPad app or Church Center. This is the biggest constraint for integration.

Data Model Hierarchy

Key Read Endpoints

Useful Check-In Queries

# Recent check-ins with person and event data sideloaded
GET /check-ins/v2/check_ins
  ?include=event,person,locations
  &order=-checked_out_at
  &per_page=100

# Headcounts by event time
GET /check-ins/v2/event_times
  ?include=headcounts
  &filter=future

Location Model (Hierarchical)

PCO Locations are hierarchical: a Location with kind="Folder" contains child locations. Each location has age/grade filtering: age_min_in_months, age_max_in_months, grade_min, grade_max, gender, child_or_adult, max_occupancy, min_volunteers, attendees_per_volunteer.

This is analogous to Church Management Platform's hierarchical church_group system with parent_group_id, but PCO uses it for room-based assignment rather than organizational-group-based event resolution.

Calendar API Read-Only

Calendar events and instances are read-only. Events are created and managed in PCO Calendar admin.

Key Endpoints

Resource Booking

PCO Calendar includes room/resource booking with ResourceBooking, Resource, ResourceFolder, and ResourceApprovalGroup resources. All read-only via API but useful for pulling room assignment data into Church Management Platform's locations.

Entity Mapping

Side-by-side comparison of Church Management Platform entities and their PCO equivalents.

Model Differences & Gaps

Family / Household Structure

• PCO HouseholdMembership has no relationship role (no Parent/Child/Spouse). PCO determines child status from the Person's child boolean flag.
• PCO addresses are on Person (not Household). Each person can have multiple addresses. Your system stores address on families.
• Your authorized_pickup_ids JSONB array has no PCO equivalent.
• Your relationships table (Parent, Child, Guardian, Spouse, Grandparent) has no PCO match.

Groups

• Your 3-level hierarchy (Department → Area → Group via church_group.level) is richer than PCO's flat GroupType → Group.
• PCO membership role is only "leader" or "member" — no equivalent to your small_group_leader_type (Leader/Coach/Other).
• Your small group metadata (meeting day, frequency, time, area, childcare, demographics) has no PCO equivalent. PCO stores schedule as a single freetext string.
• PCO enrollment_strategy and enrollment_open map loosely to your join_rule_id.

Check-Ins

• PCO uses a Station model (physical iPads) vs. your software kiosk.
• PCO resolves children to rooms via Location age/grade filters. Your system uses hierarchical group-based event resolution (walking parent_group_id chain).
• Your smart check-in window (5h/30min logic) has no PCO equivalent — PCO uses manual shows_at/hides_at configuration per station.
• PCO Headcounts are a separate concept from individual check-ins — aggregate counts by AttendanceType (e.g. "Regulars", "Guests", "Volunteers").

Events / Calendar

• PCO Calendar Event → EventInstance maps to your recurrence_group_id system.
• Your events.group_id (linking events to church groups for kiosk auto-resolution) has no PCO equivalent. PCO has separate Check-Ins Events and Calendar Events (can be integrated but distinct).

Webhooks

PCO supports webhooks for real-time change notifications, reducing the need for polling.

Available Events

Confirmed for the People module:

Check-Ins webhooks have been requested but not confirmed as available (GitHub issue #1332 closed without resolution).

Webhook Payload

{
  "data": [{
    "id": "webhook-delivery-id",
    "attributes": {
      "name": "people.v2.events.person.updated",
      "payload": {
        "data": {
          "type": "Person",
          "id": "12345",
          "attributes": { ... }
        }
      }
    }
  }]
}

Security

• Verify via X-PCO-Webhooks-Authenticity header using HMAC-SHA256 with your webhook secret.
• Use timing-safe comparison to prevent timing attacks.

Retry Policy

• Up to 16 retries with exponential backoff over 5+ days.
• Email alerts after 1 hour of failure and after final attempt.
• Subscription auto-deactivated after all retries exhausted.

Rate Limits & Pagination

Rate Limit: 100 Requests / Minute

PCO enforces 100 requests per minute per organization. No documented burst allowance. No batch/bulk endpoints exist — each person, email, phone, address, household requires its own API call.

Impact on Bulk Operations

Pagination

• Max per_page=100.
• Cursor-based via links.next URL in response. No offset parameter.
• Must follow links.next URLs sequentially — cannot jump to page N.

Mitigation Strategies

• Sideload aggressively — ?include=emails,phone_numbers,addresses to get everything in one request per page.
• Incremental sync — use ?where[updated_at][gte]=2026-02-20T00:00:00Z to pull only records changed since last sync.
• Webhooks for real-time — subscribe to person.created/updated events instead of polling.
• Queue writes — use a background job queue (with rate limiter) to spread write operations across time windows.
• Off-peak scheduling — run bulk syncs during low-activity hours (e.g., overnight).

Integration Strategies

Three viable approaches, depending on the church's needs:

Sync Architecture

Regardless of which strategy is chosen, the sync system would follow this general architecture.

Sync Service Components

Sync Mapping Table

CREATE TABLE pco_sync_map (
    id          SERIAL PRIMARY KEY,
    local_type  TEXT NOT NULL,       -- 'person', 'family', 'group', 'membership'
    local_id    INTEGER NOT NULL,
    pco_id      TEXT NOT NULL,        -- PCO uses string IDs
    pco_updated_at TIMESTAMPTZ,
    last_synced_at TIMESTAMPTZ,
    sync_status TEXT DEFAULT 'synced', -- 'synced', 'pending_push', 'pending_pull', 'conflict'
    UNIQUE(local_type, local_id),
    UNIQUE(local_type, pco_id)
);

Sync Flow: Pull People from PCO

Sync Flow: Push People to PCO

Conflict Resolution

For bidirectional sync, conflicts occur when both systems modify the same record between syncs.

• Last-write-wins — compare updated_at timestamps. Simplest but can lose data.
• Source-of-truth per field — e.g., PCO owns email, your system owns allergies. More complex but no data loss.
• Flag for review — mark conflicts in sync_status='conflict' for admin resolution. Safest but requires manual intervention.

Webhook Handler Endpoint

// New endpoint in a PcoWebhookController
POST /api/pco/webhook

// 1. Verify X-PCO-Webhooks-Authenticity header (HMAC-SHA256)
// 2. Parse JSON:API payload
// 3. Route by event name:
//    person.created  -> upsert into people table
//    person.updated  -> update people table
//    person.destroyed -> soft-delete (set is_active=false)
// 4. Update pco_sync_map
// 5. Return 200 OK