openapi: 3.0.3
info:
  title: Planning Center API
  description: >-
    A representative OpenAPI description of the Planning Center suite of church
    management APIs. Planning Center exposes a documented public REST API for each
    of its products - People, Services, Giving, Groups, Check-Ins, Calendar,
    Registrations, Publishing - plus a cross-product Webhooks API, all under the
    shared base host https://api.planningcenteronline.com. Every product is
    versioned under its own path prefix (for example /people/v2, /services/v2,
    /giving/v2). All responses conform to the JSON:API 1.0 specification: resource
    objects are wrapped in a top-level `data` member (an object or an array), each
    with `id`, `type`, `attributes`, and `relationships`, and collections support
    `include`, `where[]` filtering, `order`, and offset-based pagination via
    `per_page` and `offset`. Authenticate with HTTP Basic using a Personal Access
    Token (application id / secret) or with an OAuth 2.0 bearer token. A
    `User-Agent` header is required on every request.

    Endpoint coverage: the resource collections and base paths modeled here are
    grounded in Planning Center's published documentation. Individual method/path
    combinations are a representative CRUD-shaped subset; consult the live API
    reference at developer.planning.center for the authoritative, exhaustive list
    and per-resource attributes.
  version: '2.0'
  contact:
    name: Planning Center Developers
    url: https://developer.planning.center/docs/
  license:
    name: Proprietary
    url: https://www.planningcenter.com/terms
servers:
  - url: https://api.planningcenteronline.com
    description: Planning Center API (all products)
security:
  - basicAuth: []
  - oauth2:
      - people
      - services
      - giving
      - groups
      - check_ins
      - calendar
      - registrations
      - publishing
tags:
  - name: People
    description: People, households, contact info, lists, forms, and workflows.
  - name: Services
    description: Service planning - service types, plans, songs, teams.
  - name: Giving
    description: Donations, funds, batches, payment sources, and pledges.
  - name: Groups
    description: Small groups, memberships, and group events.
  - name: Check-Ins
    description: Attendance, events, locations, and stations.
  - name: Calendar
    description: Church calendaring, events, and facility resources.
  - name: Registrations
    description: Event signups, attendees, categories, and campuses.
  - name: Publishing
    description: Sermon channels, series, episodes, and speakers (read-only).
  - name: Webhooks
    description: Cross-product event subscriptions and deliveries.
paths:
  # ---------------- People ----------------
  /people/v2/people:
    get:
      operationId: listPeople
      tags: [People]
      summary: List people
      description: Lists people in the account. Supports include, where[] filters, order, and offset pagination.
      parameters:
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Include'
      responses:
        '200':
          $ref: '#/components/responses/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createPerson
      tags: [People]
      summary: Create a person
      requestBody:
        $ref: '#/components/requestBodies/JsonApiBody'
      responses:
        '201':
          $ref: '#/components/responses/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /people/v2/people/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getPerson
      tags: [People]
      summary: Get a person
      responses:
        '200':
          $ref: '#/components/responses/Resource'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePerson
      tags: [People]
      summary: Update a person
      requestBody:
        $ref: '#/components/requestBodies/JsonApiBody'
      responses:
        '200':
          $ref: '#/components/responses/Resource'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: deletePerson
      tags: [People]
      summary: Delete a person
      responses:
        '204':
          description: Deleted.
  /people/v2/people/{id}/emails:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: listPersonEmails
      tags: [People]
      summary: List a person's emails
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/emails:
    get:
      operationId: listEmails
      tags: [People]
      summary: List email addresses
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/addresses:
    get:
      operationId: listAddresses
      tags: [People]
      summary: List addresses
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/phone_numbers:
    get:
      operationId: listPhoneNumbers
      tags: [People]
      summary: List phone numbers
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/households:
    get:
      operationId: listHouseholds
      tags: [People]
      summary: List households
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/lists:
    get:
      operationId: listLists
      tags: [People]
      summary: List people lists
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/field_definitions:
    get:
      operationId: listFieldDefinitions
      tags: [People]
      summary: List custom field definitions
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/forms:
    get:
      operationId: listForms
      tags: [People]
      summary: List forms
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /people/v2/workflows:
    get:
      operationId: listWorkflows
      tags: [People]
      summary: List workflows
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Services ----------------
  /services/v2/service_types:
    get:
      operationId: listServiceTypes
      tags: [Services]
      summary: List service types
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /services/v2/service_types/{service_type_id}/plans:
    parameters:
      - name: service_type_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: listPlans
      tags: [Services]
      summary: List plans for a service type
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /services/v2/service_types/{service_type_id}/plans/{plan_id}:
    parameters:
      - name: service_type_id
        in: path
        required: true
        schema: { type: string }
      - name: plan_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: getPlan
      tags: [Services]
      summary: Get a plan
      responses:
        '200':
          $ref: '#/components/responses/Resource'
  /services/v2/songs:
    get:
      operationId: listSongs
      tags: [Services]
      summary: List songs
      responses:
        '200':
          $ref: '#/components/responses/Collection'
    post:
      operationId: createSong
      tags: [Services]
      summary: Create a song
      requestBody:
        $ref: '#/components/requestBodies/JsonApiBody'
      responses:
        '201':
          $ref: '#/components/responses/Resource'
  /services/v2/teams:
    get:
      operationId: listTeams
      tags: [Services]
      summary: List teams
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /services/v2/people:
    get:
      operationId: listServicesPeople
      tags: [Services]
      summary: List people in Services
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Giving ----------------
  /giving/v2/donations:
    get:
      operationId: listDonations
      tags: [Giving]
      summary: List donations
      responses:
        '200':
          $ref: '#/components/responses/Collection'
    post:
      operationId: createDonation
      tags: [Giving]
      summary: Create a donation
      description: Create a donation, including its designations to one or more funds and a payment source.
      requestBody:
        $ref: '#/components/requestBodies/JsonApiBody'
      responses:
        '201':
          $ref: '#/components/responses/Resource'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /giving/v2/donations/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getDonation
      tags: [Giving]
      summary: Get a donation
      responses:
        '200':
          $ref: '#/components/responses/Resource'
  /giving/v2/donations/{id}/issue_refund:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      operationId: issueRefund
      tags: [Giving]
      summary: Issue a refund for a donation
      responses:
        '200':
          $ref: '#/components/responses/Resource'
  /giving/v2/funds:
    get:
      operationId: listFunds
      tags: [Giving]
      summary: List funds
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /giving/v2/batches:
    get:
      operationId: listBatches
      tags: [Giving]
      summary: List batches
      responses:
        '200':
          $ref: '#/components/responses/Collection'
    post:
      operationId: createBatch
      tags: [Giving]
      summary: Create a batch
      requestBody:
        $ref: '#/components/requestBodies/JsonApiBody'
      responses:
        '201':
          $ref: '#/components/responses/Resource'
  /giving/v2/payment_sources:
    get:
      operationId: listPaymentSources
      tags: [Giving]
      summary: List payment sources
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /giving/v2/recurring_donations:
    get:
      operationId: listRecurringDonations
      tags: [Giving]
      summary: List recurring donations
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /giving/v2/pledges:
    get:
      operationId: listPledges
      tags: [Giving]
      summary: List pledges
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Groups ----------------
  /groups/v2/groups:
    get:
      operationId: listGroups
      tags: [Groups]
      summary: List groups
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /groups/v2/groups/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getGroup
      tags: [Groups]
      summary: Get a group
      responses:
        '200':
          $ref: '#/components/responses/Resource'
  /groups/v2/group_types:
    get:
      operationId: listGroupTypes
      tags: [Groups]
      summary: List group types
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /groups/v2/groups/{group_id}/memberships:
    parameters:
      - name: group_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: listGroupMemberships
      tags: [Groups]
      summary: List memberships for a group
      responses:
        '200':
          $ref: '#/components/responses/Collection'
    post:
      operationId: createGroupMembership
      tags: [Groups]
      summary: Add a member to a group
      requestBody:
        $ref: '#/components/requestBodies/JsonApiBody'
      responses:
        '201':
          $ref: '#/components/responses/Resource'
  /groups/v2/events:
    get:
      operationId: listGroupEvents
      tags: [Groups]
      summary: List group events
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Check-Ins ----------------
  /check-ins/v2/check_ins:
    get:
      operationId: listCheckIns
      tags: [Check-Ins]
      summary: List check-ins
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /check-ins/v2/events:
    get:
      operationId: listCheckInEvents
      tags: [Check-Ins]
      summary: List check-in events
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /check-ins/v2/events/{event_id}/event_times:
    parameters:
      - name: event_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: listEventTimes
      tags: [Check-Ins]
      summary: List event times for an event
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /check-ins/v2/locations:
    get:
      operationId: listCheckInLocations
      tags: [Check-Ins]
      summary: List check-in locations
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /check-ins/v2/stations:
    get:
      operationId: listStations
      tags: [Check-Ins]
      summary: List stations
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Calendar ----------------
  /calendar/v2/events:
    get:
      operationId: listCalendarEvents
      tags: [Calendar]
      summary: List calendar events
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /calendar/v2/event_instances:
    get:
      operationId: listEventInstances
      tags: [Calendar]
      summary: List event instances
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /calendar/v2/resources:
    get:
      operationId: listResources
      tags: [Calendar]
      summary: List resources (rooms and equipment)
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /calendar/v2/resource_bookings:
    get:
      operationId: listResourceBookings
      tags: [Calendar]
      summary: List resource bookings
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /calendar/v2/conflicts:
    get:
      operationId: listConflicts
      tags: [Calendar]
      summary: List scheduling conflicts
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Registrations ----------------
  /registrations/v2/signups:
    get:
      operationId: listSignups
      tags: [Registrations]
      summary: List signups
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /registrations/v2/signups/{signup_id}/attendees:
    parameters:
      - name: signup_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: listAttendees
      tags: [Registrations]
      summary: List attendees for a signup
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /registrations/v2/categories:
    get:
      operationId: listCategories
      tags: [Registrations]
      summary: List categories
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /registrations/v2/campuses:
    get:
      operationId: listCampuses
      tags: [Registrations]
      summary: List campuses
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Publishing ----------------
  /publishing/v2/channels:
    get:
      operationId: listChannels
      tags: [Publishing]
      summary: List channels
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /publishing/v2/channels/{channel_id}/episodes:
    parameters:
      - name: channel_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: listEpisodes
      tags: [Publishing]
      summary: List episodes for a channel
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /publishing/v2/series:
    get:
      operationId: listSeries
      tags: [Publishing]
      summary: List series
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /publishing/v2/speakers:
    get:
      operationId: listSpeakers
      tags: [Publishing]
      summary: List speakers
      responses:
        '200':
          $ref: '#/components/responses/Collection'

  # ---------------- Webhooks ----------------
  /webhooks/v2/subscriptions:
    get:
      operationId: listWebhookSubscriptions
      tags: [Webhooks]
      summary: List webhook subscriptions
      responses:
        '200':
          $ref: '#/components/responses/Collection'
    post:
      operationId: createWebhookSubscription
      tags: [Webhooks]
      summary: Create a webhook subscription
      description: Subscribe to an available event. Deliveries are outbound HTTPS POST to the subscription URL.
      requestBody:
        $ref: '#/components/requestBodies/JsonApiBody'
      responses:
        '201':
          $ref: '#/components/responses/Resource'
  /webhooks/v2/subscriptions/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getWebhookSubscription
      tags: [Webhooks]
      summary: Get a webhook subscription
      responses:
        '200':
          $ref: '#/components/responses/Resource'
    delete:
      operationId: deleteWebhookSubscription
      tags: [Webhooks]
      summary: Delete a webhook subscription
      responses:
        '204':
          description: Deleted.
  /webhooks/v2/available_events:
    get:
      operationId: listAvailableEvents
      tags: [Webhooks]
      summary: List available webhook events
      responses:
        '200':
          $ref: '#/components/responses/Collection'
  /webhooks/v2/subscriptions/{subscription_id}/events:
    parameters:
      - name: subscription_id
        in: path
        required: true
        schema: { type: string }
    get:
      operationId: listWebhookDeliveries
      tags: [Webhooks]
      summary: List delivered events for a subscription
      responses:
        '200':
          $ref: '#/components/responses/Collection'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth using a Personal Access Token - application id as the username and secret as the password.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.planningcenteronline.com/oauth/authorize
          tokenUrl: https://api.planningcenteronline.com/oauth/token
          scopes:
            people: Access the People product
            services: Access the Services product
            giving: Access the Giving product
            groups: Access the Groups product
            check_ins: Access the Check-Ins product
            calendar: Access the Calendar product
            registrations: Access the Registrations product
            publishing: Access the Publishing product
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema: { type: string }
      description: The resource ID.
    PerPage:
      name: per_page
      in: query
      required: false
      schema: { type: integer, default: 25, maximum: 100 }
      description: Number of records per page (JSON:API pagination).
    Offset:
      name: offset
      in: query
      required: false
      schema: { type: integer, default: 0 }
      description: Zero-based offset for pagination. Offsets above 30,000 are subject to a stricter rate limit.
    Include:
      name: include
      in: query
      required: false
      schema: { type: string }
      description: Comma-separated list of related resources to sideload (JSON:API include).
  requestBodies:
    JsonApiBody:
      required: true
      description: A JSON:API single-resource document.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonApiResourceDocument'
  responses:
    Resource:
      description: A single JSON:API resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonApiResourceDocument'
    Collection:
      description: A JSON:API collection of resources.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonApiCollectionDocument'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorDocument'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorDocument'
    UnprocessableEntity:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorDocument'
    RateLimited:
      description: Rate limit exceeded (100 requests per 20 seconds per user).
      headers:
        Retry-After:
          schema: { type: integer }
          description: Seconds to wait before retrying.
        X-PCO-API-Request-Rate-Limit:
          schema: { type: integer }
        X-PCO-API-Request-Rate-Period:
          schema: { type: integer }
        X-PCO-API-Request-Rate-Count:
          schema: { type: integer }
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonApiErrorDocument'
  schemas:
    JsonApiResource:
      type: object
      description: A JSON:API resource object.
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
          additionalProperties: true
        relationships:
          type: object
          additionalProperties: true
        links:
          type: object
          additionalProperties: true
    JsonApiResourceDocument:
      type: object
      required: [data]
      properties:
        data:
          $ref: '#/components/schemas/JsonApiResource'
        included:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiResource'
    JsonApiCollectionDocument:
      type: object
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiResource'
        included:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiResource'
        meta:
          type: object
          properties:
            total_count:
              type: integer
            count:
              type: integer
        links:
          type: object
          properties:
            self:
              type: string
            next:
              type: string
    JsonApiErrorDocument:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              title:
                type: string
              detail:
                type: string