### Example Organization API Request

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/organization

Demonstrates how to make a basic GET request to the Organization API endpoint.

```bash
curl https://api.planningcenteronline.com/calendar/v2
```

--------------------------------

### ListResult Example Request

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/list_result

Shows how to make a GET request to list list results for a specific list.

```curl
curl https://api.planningcenteronline.com/people/v2/lists/{list_id}/list_results
```

--------------------------------

### Resource Suggestion Object Example

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource_suggestion

This is an example of the JSON object representing a resource suggestion. It includes details about the suggested resource, quantity, and associated room setup.

```json
{
  "type": "ResourceSuggestion",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "quantity": 1,
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "resource": {
      "data": {
        "type": "Resource",
        "id": "1"
      }
    },
    "room_setup": {
      "data": {
        "type": "RoomSetup",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### List School Options

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/school_option

Use this endpoint to retrieve a list of all school options. No specific setup is required beyond making the GET request.

```bash
curl https://api.planningcenteronline.com/people/v2/school_options
```

--------------------------------

### Example Request to List Batches

Source: https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/batch

Use this cURL command to make a GET request to the batches endpoint.

```bash
curl https://api.planningcenteronline.com/giving/v2/batches
```

--------------------------------

### Example Request for Public View

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/public_view

Demonstrates how to make a GET request to retrieve public view settings for a specific service type. Replace `{service_type_id}` with the actual ID.

```curl
curl https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/public_view
```

--------------------------------

### Install Add-ons CLI Tool

Source: https://api.planningcenteronline.com/docs/overview/add-ons/building-your-first-add-on

Installs the PlanningCenter add-ons CLI tool globally using npm. Ensure Node.js and npm are installed beforehand.

```bash
npm install --global @planningcenter/add-ons-cli
```

--------------------------------

### List Room Setups

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/room_setup

Use this endpoint to retrieve a list of all room setups. No specific setup is required.

```curl
curl https://api.planningcenteronline.com/calendar/v2/room_setups
```

--------------------------------

### Get Room Setup for an Event Resource Request

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/event_resource_request

Retrieves the room setup details for a specific event resource request.

```APIDOC
## GET /calendar/v2/event_resource_requests/{event_resource_request_id}/room_setup

### Description
Retrieves the room setup details for a specific event resource request.

### Method
GET

### Endpoint
https://api.planningcenteronline.com/calendar/v2/event_resource_requests/{event_resource_request_id}/room_setup

### Parameters
#### Path Parameters
- **event_resource_request_id** (integer) - Required - The ID of the event resource request.
```

--------------------------------

### config.yaml Example

Source: https://api.planningcenteronline.com/docs/overview/add-ons/add-ons-cli

Example configuration file for a Planning Center add-on. This YAML file defines OAuth settings and UI extensions for different deployment environments.

```yaml
testing_oauth_config: &testing_oauth_config
  authorize_url: http://myapp.local/oauth/authorize
  token_url: http://myapp.local/oauth/token
  redirect_url: http://myapp.local/oauth/complete
  identifier: "{{ TESTING_INTEGRATOR_OAUTH_IDENTIFIER }}"
  secret: "{{ TESTING_INTEGRATOR_OAUTH_SECRET }}"
  scopes: []

production_oauth_config: &production_oauth_config
  authorize_url: https://example.com/oauth/authorize
  token_url: https://example.com/oauth/token
  redirect_url: https://example.com/oauth/complete
  identifier: "{{ PRODUCTION_INTEGRATOR_OAUTH_IDENTIFIER }}"
  secret: "{{ PRODUCTION_INTEGRATOR_OAUTH_SECRET }}"
  scopes: []

add_on:
  oauth_application_id: "300"
  environments:
    testing:
      integrator_oauth: *testing_oauth_config
    beta:
      integrator_oauth: *production_oauth_config
      ui_extensions:
        - people.list.send_message
      organization_ids: []
    production:
      integrator_oauth: *production_oauth_config
      ui_extensions:
        - people.list.send_message
  scopes:
    - people
  ui_extensions:
    people.list.send_message:
      title: Send text with Foo
      icon_url: data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMjAgMjAiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGNpcmNsZSBjeD0iMTAiIGN5PSIxMCIgcj0iOCIgc3Ryb2tlPSJoc2woMjY4LCA3MSUsIDI3JSkiIHN0cm9rZS13aWR0aD0iMiIgZmlsbD0ibm9uZSIvPjwvc3ZnPg==
      icon_dark_url: data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMjAgMjAiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGNpcmNsZSBjeD0iMTAiIGN5PSIxMCIgcj0iOCIgc3Ryb2tlPSJoc2woMjY4LCA3MCUsIDg4JSkiIHN0cm9rZS13aWR0aD0iMiIgZmlsbD0ibm9uZSIvPjwvc3ZnPg==
      component_version: "6"
```

--------------------------------

### List Room Setups

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource

Retrieves a list of room setups for a specific resource.

```APIDOC
## GET /calendar/v2/resources/{resource_id}/room_setups

### Description
Retrieves a list of room setups for a specific resource.

### Method
GET

### Endpoint
https://api.planningcenteronline.com/calendar/v2/resources/{resource_id}/room_setups

### Parameters
#### Path Parameters
- **resource_id** (integer) - Required - The ID of the resource.
```

--------------------------------

### Example FolderPath Object

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/folder_path

This is an example of the FolderPath object structure returned by the API.

```json
{
  "type": "FolderPath",
  "id": "1",
  "attributes": {
    "path": []
  },
  "relationships": {}
}
```

--------------------------------

### List Room Setups

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/organization

Retrieves a list of room setups. Supports filtering for shared room setups.

```APIDOC
## GET https://api.planningcenteronline.com/calendar/v2/room_setups

### Description
Retrieves a list of room setups. Supports filtering for shared room setups.

### Method
GET

### Endpoint
https://api.planningcenteronline.com/calendar/v2/room_setups

### Parameters
#### Query Parameters
- **shared_room_setups** (boolean) - Optional - Filter for shared room setups.

### Returns
RoomSetup
```

--------------------------------

### Read Room Setup

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/room_setup

Retrieves a specific room setup by its ID.

```APIDOC
## GET /calendar/v2/room_setups/{id}

### Description
Retrieves a specific room setup by its unique identifier.

### Method
GET

### Endpoint
`/calendar/v2/room_setups/{id}`

### Parameters
#### Path Parameters
- **id** (primary_key) - Required - Unique identifier for the room setup.

### Response
#### Success Response (200)
- `data` (object) - The requested RoomSetup object.

### Response Example
```json
{
  "data": {
    "type": "RoomSetup",
    "id": "1",
    "attributes": {
      "created_at": "2000-01-01T12:00:00Z",
      "description": "string",
      "diagram": "string",
      "diagram_thumbnail_url": "string",
      "diagram_url": "string",
      "name": "string",
      "updated_at": "2000-01-01T12:00:00Z"
    },
    "relationships": {
      "room_setup": {"data": {"type": "RoomSetup", "id": "1"}},
      "resource_suggestions": {"data": [{"type": "ResourceSuggestion", "id": "1"}]},
      "containing_resource": {"data": {"type": "Resource", "id": "1"}}
    }
  }
}
```
```

--------------------------------

### Example Location Request

Source: https://api.planningcenteronline.com/docs/apps/groups/versions/2023-07-10/vertices/location

This snippet shows how to make a GET request to retrieve location information for a specific event. Replace `{event_id}` with the actual event ID.

```bash
curl https://api.planningcenteronline.com/groups/v2/events/{event_id}/location
```

--------------------------------

### Example Request for Workflow Assignee Summaries

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/workflow_assignee_summary

Use this cURL command to fetch workflow assignee summaries. This is a basic GET request to the API endpoint.

```bash
curl https://api.planningcenteronline.com/people/v2/workflow_assignee_summaries
```

--------------------------------

### Room Setup Associations

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/room_setup

Endpoints for accessing associated resources and suggestions for a given room setup.

```APIDOC
## GET /calendar/v2/room_setups/{room_setup_id}/containing_resource

### Description
Retrieves the containing resource associated with a specific room setup.

### Method
GET

### Endpoint
`/calendar/v2/room_setups/{room_setup_id}/containing_resource`

### Parameters
#### Path Parameters
- **room_setup_id** (primary_key) - Required - The ID of the room setup.

## GET /calendar/v2/room_setups/{room_setup_id}/resource_suggestions

### Description
Retrieves the list of resource suggestions associated with a specific room setup.

### Method
GET

### Endpoint
`/calendar/v2/room_setups/{room_setup_id}/resource_suggestions`

### Parameters
#### Path Parameters
- **room_setup_id** (primary_key) - Required - The ID of the room setup.
```

--------------------------------

### List Room Setups

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/room_setup

Retrieves a list of all available room setups. Supports filtering, ordering, and pagination.

```APIDOC
## GET /calendar/v2/room_setups

### Description
Retrieves a list of room setups. This endpoint supports filtering by attributes, ordering the results, and paginating the response.

### Method
GET

### Endpoint
`/calendar/v2/room_setups`

### Query Parameters
#### Filtering
- `where[created_at]` (date_time) - Optional - Query on a specific created_at date.
- `where[name]` (string) - Optional - Query on a specific name.
- `where[updated_at]` (date_time) - Optional - Query on a specific updated_at date.

#### Ordering
- `order` (string) - Optional - Specify the order of results. Prefix with a hyphen (-) to reverse the order (e.g., `-created_at`).
  - `created_at`
  - `name`
  - `updated_at`

#### Pagination
- `per_page` (integer) - Optional - Number of records to return per page (min=1, max=100, default=25).
- `offset` (integer) - Optional - Get results starting from the given offset.

### Response
#### Success Response (200)
- `data` (array) - An array of RoomSetup objects.
- `meta` (object) - Pagination and other metadata.

### Response Example
```json
{
  "data": [
    {
      "type": "RoomSetup",
      "id": "1",
      "attributes": {
        "created_at": "2000-01-01T12:00:00Z",
        "description": "string",
        "diagram": "string",
        "diagram_thumbnail_url": "string",
        "diagram_url": "string",
        "name": "string",
        "updated_at": "2000-01-01T12:00:00Z"
      },
      "relationships": {
        "room_setup": {"data": {"type": "RoomSetup", "id": "1"}},
        "resource_suggestions": {"data": [{"type": "ResourceSuggestion", "id": "1"}]},
        "containing_resource": {"data": {"type": "Resource", "id": "1"}}
      }
    }
  ],
  "meta": {
    "count": 1
  }
}
```
```

--------------------------------

### List Star Example Request

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/list_star

This snippet shows an example of how to make a request to star a list.

```curl
curl https://api.planningcenteronline.com/people/v2/lists/{list_id}/star
```

--------------------------------

### Signup Time Object Structure

Source: https://api.planningcenteronline.com/docs/apps/registrations/versions/2025-05-01/vertices/signup_time

This is an example of the SignupTime object returned by the API. It includes attributes like start and end times, and whether it's an all-day event.

```json
{
  "type": "SignupTime",
  "id": "1",
  "attributes": {
    "all_day": true,
    "created_at": "2000-01-01T12:00:00Z",
    "ends_at": "2000-01-01T12:00:00Z",
    "starts_at": "2000-01-01T12:00:00Z",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}
```

--------------------------------

### Query by First Name Example

Source: https://api.planningcenteronline.com/docs/apps/groups/versions/2023-07-10/vertices/person

This example shows how to query for people using their first name. Append `?where[first_name]=string` to the base URL to filter results.

```http
?where[first_name]=string
```

--------------------------------

### Room Setup Belongs To

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/room_setup

Endpoints for accessing the parent resource or organization a room setup belongs to.

```APIDOC
## GET /calendar/v2/event_resource_requests/{event_resource_request_id}/room_setup

### Description
Retrieves the room setup associated with a specific event resource request.

### Method
GET

### Endpoint
`/calendar/v2/event_resource_requests/{event_resource_request_id}/room_setup`

### Parameters
#### Path Parameters
- **event_resource_request_id** (primary_key) - Required - The ID of the event resource request.

## GET /calendar/v2/room_setups

### Description
Retrieves the organization that the room setup belongs to. This endpoint can also be used to query shared room setups.

### Method
GET

### Endpoint
`/calendar/v2/room_setups`

### Query Parameters
#### Filtering
- `filter[shared_room_setups]` (boolean) - Optional - Filter for shared room setups.

## GET /calendar/v2/resources/{resource_id}/room_setups

### Description
Retrieves the room setups associated with a specific resource.

### Method
GET

### Endpoint
`/calendar/v2/resources/{resource_id}/room_setups`

### Parameters
#### Path Parameters
- **resource_id** (primary_key) - Required - The ID of the resource.
```

--------------------------------

### Query by Last Name Example

Source: https://api.planningcenteronline.com/docs/apps/groups/versions/2023-07-10/vertices/person

This example demonstrates how to query for people using their last name. Append `?where[last_name]=string` to the base URL to filter results.

```http
?where[last_name]=string
```

--------------------------------

### Example MAU Object

Source: https://api.planningcenteronline.com/docs/apps/api/versions/2025-09-30/vertices/oauth_application_mau

This is an example of the JSON object returned for a Monthly Active User stat.

```json
{
  "type": "OauthApplicationMau",
  "id": "1",
  "attributes": {
    "count": 1,
    "month": 1,
    "year": 1
  },
  "relationships": {
    "oauth_application": {
      "data": {
        "type": "OauthApplication",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### Room Setup Object Structure

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/room_setup

This is the structure of a Room Setup object, showing its attributes and relationships. It includes details like creation time, description, and URLs for diagrams.

```json
{
  "type": "RoomSetup",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "diagram": "string",
    "diagram_thumbnail_url": "string",
    "diagram_url": "string",
    "name": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "room_setup": {
      "data": {
        "type": "RoomSetup",
        "id": "1"
      }
    },
    "resource_suggestions": {
      "data": [
        {
          "type": "ResourceSuggestion",
          "id": "1"
        }
      ]
    },
    "containing_resource": {
      "data": {
        "type": "Resource",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### Example Arrangement Section Object

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/arrangement_sections

This is an example of the JSON object returned when querying arrangement sections. It includes the type, ID, attributes, and relationships.

```json
{
  "type": "ArrangementSections",
  "id": "1",
  "attributes": {
    "sections": []
  },
  "relationships": {}
}
```

--------------------------------

### Create and Navigate to New Add-on Directory

Source: https://api.planningcenteronline.com/docs/overview/add-ons/building-your-first-add-on

Creates a new add-on project using the CLI and changes the current directory into the new add-on's folder.

```bash
planningcenter-add-ons create my-add-on
cd my-add-on
```

--------------------------------

### Example Request for AttachmentActivity

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/attachment_activity

Use this cURL command to make a GET request to the AttachmentActivity collection endpoint.

```bash
curl https://api.planningcenteronline.com/services/v2
```

--------------------------------

### Example Organization Request

Source: https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/organization

Demonstrates how to make a request to the Giving API to retrieve organization data.

```bash
curl https://api.planningcenteronline.com/giving/v2
```

--------------------------------

### Example Name Prefix Object

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/name_prefix

This is an example of the JSON object structure returned when retrieving a name prefix. It includes the type, ID, attributes, and relationships.

```json
{
  "type": "NamePrefix",
  "id": "1",
  "attributes": {
    "value": "string"
  },
  "relationships": {}
}
```

--------------------------------

### Signup Object Structure

Source: https://api.planningcenteronline.com/docs/apps/registrations/versions/2025-05-01/vertices/signup

This is an example of a Signup object, illustrating its attributes and relationships. Note the various date-time fields and capacity information.

```json
{
  "type": "Signup",
  "id": "1",
  "attributes": {
    "archived": true,
    "at_maximum_capacity": true,
    "close_at": "2000-01-01T12:00:00Z",
    "closed": true,
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "logo_url": "string",
    "maximum_capacity": 1,
    "name": "string",
    "new_registration_url": "string",
    "open": true,
    "open_at": "2000-01-01T12:00:00Z",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}
```

--------------------------------

### Create a Resource Folder

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource_folder

Create a new resource folder by sending a POST request with the folder's kind and name. The 'kind' can be 'Room' or 'Resource'.

```bash
curl -X POST https://api.planningcenteronline.com/calendar/v2/resource_folders -d '{"name": "string", "kind": "string"}'
```

--------------------------------

### Get PledgeCampaign

Source: https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/pledge_campaign

Example of how to retrieve a specific PledgeCampaign using its ID. Replace `{person_id}` and `{pledge_id}` with actual IDs.

```bash
curl https://api.planningcenteronline.com/giving/v2/people/{person_id}/pledges/{pledge_id}/pledge_campaign
```

--------------------------------

### Get Resource by Resource Suggestion ID

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource

Retrieves a specific resource associated with a resource suggestion within a room setup.

```APIDOC
## GET /calendar/v2/room_setups/{room_setup_id}/resource_suggestions/{resource_suggestion_id}/resource

### Description
Retrieves a specific resource associated with a resource suggestion within a room setup.

### Method
GET

### Endpoint
https://api.planningcenteronline.com/calendar/v2/room_setups/{room_setup_id}/resource_suggestions/{resource_suggestion_id}/resource
```

--------------------------------

### List Resource Questions

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource_question

Use this endpoint to retrieve a list of all resource questions. No specific setup is required beyond authentication.

```bash
curl https://api.planningcenteronline.com/calendar/v2/resource_questions
```

--------------------------------

### Example ChannelNextTime Object

Source: https://api.planningcenteronline.com/docs/apps/publishing/versions/2024-03-25/vertices/channel_next_time

This is the structure of a ChannelNextTime object returned by the API. It includes the type, ID, and attributes such as the start time.

```json
{
  "type": "ChannelNextTime",
  "id": "1",
  "attributes": {
    "starts_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}
```

--------------------------------

### List Stations - cURL Example

Source: https://api.planningcenteronline.com/docs/apps/check-ins/versions/2025-05-28/vertices/station

Use this cURL command to make a GET request to the /check-ins/v2/stations endpoint to retrieve a list of all stations.

```bash
curl https://api.planningcenteronline.com/check-ins/v2/stations
```

--------------------------------

### Mount React app with onRender

Source: https://api.planningcenteronline.com/docs/overview/add-ons/api-reference

Use `onRender` as the main entry point to mount your React app. It receives an `args` object with rendering context and should return JSX.

```javascript
import { Avatar, Button, Text } from '@planningcenter/add-ons-ui';

onRender((args) => {
  const { location, closeModal, currentPersonId, currentOrganizationId } = args;

  console.log('Rendering at:', location);
  console.log('Current person:', currentPersonId);
  console.log('Current organization:', currentOrganizationId);

  return (
    <>
      <Text>Hello from {location}!</Text>
      <Button onClick={() => closeModal()}>Close</Button>
    </>
  );
});
```

--------------------------------

### EventTime Object Structure

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/event_time

This is an example of the JSON structure for an EventTime object. It includes attributes like start and end times, and relationships to other objects.

```json
{
  "type": "EventTime",
  "id": "1",
  "attributes": {
    "ends_at": "2000-01-01T12:00:00Z",
    "name": "string",
    "starts_at": "2000-01-01T12:00:00Z",
    "visible_on_kiosks": true,
    "visible_on_widget_and_ical": true
  },
  "relationships": {
    "event": {
      "data": {
        "type": "Event",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### PlanTime Object Structure

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/plan_time

This is an example of the PlanTime object returned by the API. It includes attributes like start and end times, and relationships to teams and positions.

```json
{
  "type": "PlanTime",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "ends_at": "2000-01-01T12:00:00Z",
    "live_ends_at": "2000-01-01T12:00:00Z",
    "live_starts_at": "2000-01-01T12:00:00Z",
    "name": "string",
    "recorded": true,
    "scheduled_team_ids": [],
    "starts_at": "2000-01-01T12:00:00Z",
    "team_reminders": [],
    "time_type": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "assigned_teams": {
      "data": [
        {
          "type": "Team",
          "id": "1"
        }
      ]
    },
    "assigned_positions": {
      "data": [
        {
          "type": "TeamPosition",
          "id": "1"
        }
      ]
    }
  }
}
```

--------------------------------

### List Options - cURL

Source: https://api.planningcenteronline.com/docs/apps/check-ins/versions/2025-05-28/vertices/option

Use this endpoint to retrieve a list of all available options. No specific setup is required beyond having access to the API.

```bash
curl https://api.planningcenteronline.com/check-ins/v2/options
```

--------------------------------

### Example Organization Request

Source: https://api.planningcenteronline.com/docs/apps/groups/versions/2023-07-10/vertices/organization

Use this cURL command to make a request to the Organization endpoint.

```bash
curl https://api.planningcenteronline.com/groups/v2
```

--------------------------------

### Signup Sheet Metadata Object Structure

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/signup_sheet_metadata

This is an example of the SignupSheetMetadata object returned by the API. It includes attributes like conflicts, start and end times, and time names.

```json
{
  "type": "SignupSheetMetadata",
  "id": "1",
  "attributes": {
    "conflicts": {},
    "ends_at": "2000-01-01T12:00:00Z",
    "starts_at": "2000-01-01T12:00:00Z",
    "time_name": "string",
    "time_type": "string"
  },
  "relationships": {
    "plan_time": {
      "data": {
        "type": "PlanTime",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### EventInstance Object Structure

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/event_instance

This is an example of the EventInstance object returned by the API. It includes attributes like start and end times, recurrence information, and associated event details.

```json
{
  "type": "EventInstance",
  "id": "1",
  "attributes": {
    "all_day_event": true,
    "church_center_url": "string",
    "compact_recurrence_description": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "ends_at": "2000-01-01T12:00:00Z",
    "image_url": "string",
    "kind": "string",
    "location": "string",
    "name": "string",
    "published_ends_at": "string",
    "published_starts_at": "string",
    "recurrence": "string",
    "recurrence_description": "string",
    "starts_at": "2000-01-01T12:00:00Z",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "event": {
      "data": {
        "type": "Event",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### JSON API: Filtering by String Prefix

Source: https://api.planningcenteronline.com/docs/overview/json-api

To match a partial string, append a URL-encoded '%' character to the value. This example finds people whose first name starts with 'Tim'.

```http
https://api.planningcenteronline.com/people/v2/people?where[first_name]=Tim%25
```

--------------------------------

### Query Media by Title

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/media

Example of how to query media assets filtered by a specific title.

```bash
?where[title]=string
```

--------------------------------

### Query Resource Questions by Created At

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource_question

Example of how to filter resource questions based on their creation date. Ensure the date format is correct.

```bash
curl "https://api.planningcenteronline.com/calendar/v2/resource_questions?where[created_at]=2000-01-01T12:00:00Z"
```

--------------------------------

### RecurringDonation Object Example

Source: https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/recurring_donation

This is an example of the structure of a RecurringDonation object returned by the API.

```json
{
  "type": "RecurringDonation",
  "id": "1",
  "attributes": {
    "amount_cents": 1,
    "amount_currency": "USD",
    "created_at": "2000-01-01T12:00:00Z",
    "last_donation_received_at": "2000-01-01T12:00:00Z",
    "next_occurrence": "2000-01-01T12:00:00Z",
    "release_hold_at": "2000-01-01T12:00:00Z",
    "schedule": {
      "day_in_month": {
        "day": 1
      }
    },
    "status": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "person": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### PeopleImport Object Example

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/people_import

This is an example of the PeopleImport object structure, showing its attributes and relationships.

```json
{
  "type": "PeopleImport",
  "id": "1",
  "attributes": {
    "attribs": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "processed_at": "2000-01-01T12:00:00Z",
    "status": "value",
    "undone_at": "2000-01-01T12:00:00Z",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "created_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "undone_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### Example Public View Object

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/public_view

Shows the structure of a PublicView object returned by the API, detailing various display options.

```json
{
  "type": "PublicView",
  "id": "1",
  "attributes": {
    "amazon": true,
    "headers": true,
    "item_descriptions": true,
    "item_lengths": true,
    "itunes": true,
    "media_items": true,
    "regular_items": true,
    "series_and_plan_titles": true,
    "series_artwork": true,
    "service_times": true,
    "song_items": true,
    "spotify": true,
    "vimeo": true,
    "youtube": true
  },
  "relationships": {}
}
```

--------------------------------

### Example Marital Status Object

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/marital_status

This is an example of the JSON object structure for a marital status.

```json
{
  "type": "MaritalStatus",
  "id": "1",
  "attributes": {
    "value": "string"
  },
  "relationships": {}
}
```

--------------------------------

### Example Request to Live Endpoint

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/live

Use this cURL command to make a request to the Live endpoint for a specific series and plan.

```bash
curl https://api.planningcenteronline.com/services/v2/series/{series_id}/plans/{plan_id}/live
```

--------------------------------

### Get Organization for Notes

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/note

Retrieve the Organization to which the notes belong using this GET endpoint.

```HTTP
GET https://api.planningcenteronline.com/people/v2/notes
```

--------------------------------

### Example Enrollment Request

Source: https://api.planningcenteronline.com/docs/apps/groups/versions/2023-07-10/vertices/enrollment

Use this cURL command to request enrollment details for a specific group. Replace `{group_id}` with the actual group ID.

```curl
curl https://api.planningcenteronline.com/groups/v2/groups/{group_id}/enrollment
```

--------------------------------

### Get Associated Person

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/note

Retrieve the Person to whom the note is attached using this GET endpoint.

```HTTP
GET https://api.planningcenteronline.com/people/v2/notes/{note_id}/person
```

--------------------------------

### addOnEnvironment

Source: https://api.planningcenteronline.com/docs/overview/add-ons/api-reference

Returns a string indicating the current environment ('testing', 'beta', or 'production'), useful for conditional logic.

```APIDOC
## `addOnEnvironment`

### Description
This function returns a string indicating which environment your add-on is currently running in. This is useful for conditional logic or debugging.

### Method
`addOnEnvironment()`

### Parameters
None

### Request Example
```javascript
const env = addOnEnvironment();
console.log(env); // "testing", "beta", or "production"

if (env === 'testing') {
  console.log('Running in testing mode');
}
```

### Response
#### Success Response
- **env** (string) - The current environment. Possible values: "testing", "beta", "production".
```

--------------------------------

### Get Associated Creator

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/note

Retrieve the Person who created the note using this GET endpoint.

```HTTP
GET https://api.planningcenteronline.com/people/v2/notes/{note_id}/created_by
```

--------------------------------

### Example Resource Object

Source: https://api.planningcenteronline.com/docs/apps/groups/versions/2023-07-10/vertices/resource

This is a sample JSON object representing a resource. It includes details like description, name, type, and relationships to other entities such as the creator.

```json
{
  "type": "Resource",
  "id": "1",
  "attributes": {
    "description": "string",
    "last_updated": "2000-01-01T12:00:00Z",
    "name": "string",
    "type": "string",
    "visibility": "value"
  },
  "relationships": {
    "created_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### Resource Booking Object Example

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource_booking

This is an example of a Resource Booking object, showing its structure and attributes. It includes details about the booking's timing, quantity, and associated events and resources.

```json
{
  "type": "ResourceBooking",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "ends_at": "2000-01-01T12:00:00Z",
    "quantity": 1,
    "starts_at": "2000-01-01T12:00:00Z",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "event": {
      "data": {
        "type": "Event",
        "id": "1"
      }
    },
    "event_instance": {
      "data": {
        "type": "EventInstance",
        "id": "1"
      }
    },
    "resource": {
      "data": {
        "type": "Resource",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### Query Resource Questions by Kind

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/resource_question

Example of how to filter resource questions by their kind. Valid kinds include 'dropdown', 'paragraph', 'text', 'yesno', and 'section_header'.

```bash
curl "https://api.planningcenteronline.com/calendar/v2/resource_questions?where[kind]=string"
```

--------------------------------

### Example Address Object

Source: https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/person

This snippet shows an example of an address object within the Person object.

```json
{
      "street_line_1": "2790 Gateway Rd",
      "street_line_2": "",
      "city": "Carlsbad",
      "state": "CA",
      "zip": "92009",
      "location": "Home",
      "primary": true,
      "street": "2790 Gateway Rd",
      "line_1": "2790 Gateway Rd",
      "line_2": "Carlsbad, CA 92009"
    }
```

--------------------------------

### Example Headcount Request

Source: https://api.planningcenteronline.com/docs/apps/check-ins/versions/2025-05-28/vertices/headcount

Use this endpoint to list headcounts. You can filter and order results using query parameters.

```bash
curl https://api.planningcenteronline.com/check-ins/v2/headcounts
```

--------------------------------

### Pledge Object Example

Source: https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/pledge

This is an example of the JSON structure for a Pledge object, including its attributes and relationships.

```json
{
  "type": "Pledge",
  "id": "1",
  "attributes": {
    "amount_cents": 1,
    "amount_currency": "USD",
    "created_at": "2000-01-01T12:00:00Z",
    "donated_total_cents": 1,
    "joint_giver_amount_cents": 1,
    "joint_giver_donated_total_cents": 1,
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "person": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "pledge_campaign": {
      "data": {
        "type": "PledgeCampaign",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### BatchGroup Object Example

Source: https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/batch_group

This is an example of the JSON object structure for a BatchGroup, including its attributes and relationships.

```json
{
  "type": "BatchGroup",
  "id": "1",
  "attributes": {
    "committed": true,
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "status": "string",
    "total_cents": 1,
    "total_currency": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}
```

--------------------------------

### List Field Options

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/field_option

Use this endpoint to retrieve a list of field options for a specific field definition. No specific setup is required beyond having a valid field definition ID.

```bash
curl https://api.planningcenteronline.com/people/v2/field_definitions/{field_definition_id}/field_options
```

--------------------------------

### TagGroup Object Example

Source: https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/tag_group

This is an example of the JSON object structure for a TagGroup, including its attributes and relationships.

```json
{
  "type": "TagGroup",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "name": "string",
    "required": true,
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}
```

--------------------------------

### Go to Next Item Action

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/live

Use this POST request to advance the live event to the next item in the sequence.

```bash
POST https://api.planningcenteronline.com/services/v2/series/{series_id}/plans/{plan_id}/live/{live_id}/go_to_next_item
```

--------------------------------

### Query Media by Creator Name

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/media

Example of how to query media assets filtered by a specific creator's name.

```bash
?where[creator_name]=string
```

--------------------------------

### Webhook Subscription Object Example

Source: https://api.planningcenteronline.com/docs/apps/webhooks/versions/2022-10-20/vertices/webhook_subscription

This is an example of the structure of a webhook subscription object, including its attributes and relationships.

```json
{
  "type": "WebhookSubscription",
  "id": "1",
  "attributes": {
    "active": true,
    "application_id": "string",
    "authenticity_secret": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "name": "string",
    "updated_at": "2000-01-01T12:00:00Z",
    "url": "string"
  },
  "relationships": {}
}
```

--------------------------------

### onRender

Source: https://api.planningcenteronline.com/docs/overview/add-ons/api-reference

The main entry point for your add-on, used to mount your React app. It receives an `args` object with rendering context.

```APIDOC
## `onRender`

### Description
This is the main entry point for your add-on. You must call this function to mount your React app. It receives an `args` object that contains context about where and how your add-on is being rendered.

### Method
`onRender(callback)`

### Parameters
- **callback** (function) - Required - A function that receives an `args` object and returns a React component or JSX.
  - **`args` Object**:
    - `location` (string) - The insertion point where your add-on is being rendered (e.g., `"people.list.send_message"`).
    - `currentPersonId` (string) - The ID of the currently logged-in user.
    - `currentOrganizationId` (string) - The ID of the current organization.
    - Additional properties specific to each insertion point.

### Request Example
```javascript
import { Avatar, Button, Text } from '@planningcenter/add-ons-ui';

onRender((args) => {
  const { location, closeModal, currentPersonId, currentOrganizationId } = args;

  console.log('Rendering at:', location);
  console.log('Current person:', currentPersonId);
  console.log('Current organization:', currentOrganizationId);

  return (
    <>
      <Text>Hello from {location}!</Text>
      <Button onClick={() => closeModal()}>Close</Button>
    </>
  );
});
```

### Response
This function does not return a value directly, but it mounts your React application.
```

--------------------------------

### Pass Object Example

Source: https://api.planningcenteronline.com/docs/apps/check-ins/versions/2025-05-28/vertices/pass

This is an example of the Pass object structure, including its type, ID, attributes, and relationships.

```json
{
  "type": "Pass",
  "id": "1",
  "attributes": {
    "code": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "kind": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}
```

--------------------------------

### Create a New Campus

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/campus

Use a POST request to create a new campus. Requires Organization Administrator privileges. Assignable attributes are listed.

```bash
POST /people/v2/campuses
```

--------------------------------

### Get Associated Note Category

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/note

Retrieve the NoteCategory associated with a specific note using this GET endpoint.

```HTTP
GET https://api.planningcenteronline.com/people/v2/notes/{note_id}/category
```

--------------------------------

### Get the current add-on environment

Source: https://api.planningcenteronline.com/docs/overview/add-ons/api-reference

Use `addOnEnvironment` to determine if your add-on is running in 'testing', 'beta', or 'production'. This is useful for conditional logic.

```javascript
const env = addOnEnvironment();
console.log(env); // "testing", "beta", or "production"

if (env === 'testing') {
  console.log('Running in testing mode');
}
```

--------------------------------

### Workflow Step Object Example

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/workflow_step

An example of the JSON structure for a Workflow Step object, including attributes and relationships.

```json
{
  "type": "WorkflowStep",
  "id": "1",
  "attributes": {
    "auto_snooze_days": 1,
    "auto_snooze_interval": "value",
    "auto_snooze_value": 1,
    "created_at": "2000-01-01T12:00:00Z",
    "default_assignee_id": "primary_key",
    "description": "string",
    "expected_response_time_in_days": 1,
    "my_ready_card_count": 1,
    "name": "string",
    "sequence": 1,
    "skip_conditions_enabled": true,
    "total_ready_card_count": 1,
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "default_assignee": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "workflow": {
      "data": {
        "type": "Workflow",
        "id": "1"
      }
    }
  }
}
```

--------------------------------

### Create a Folder

Source: https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/folder

Use a POST request to create a new folder. You can specify the name, parent ID, and campus ID as assignable attributes.

```http
POST /services/v2/folders
```

--------------------------------

### NoteCategorySubscription Object Example

Source: https://api.planningcenteronline.com/docs/apps/people/versions/2026-06-04/vertices/note_category_subscription

This is an example of the JSON object structure for a NoteCategorySubscription. It includes type, id, attributes, and relationships.

```json
{
  "type": "NoteCategorySubscription",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "person": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "note_category": {
      "data": {
        "type": "NoteCategory",
        "id": "1"
      }
    }
  }
}
```