API
⌘K
My Developer Account

Group

A group of people that meet together regularly.

Example Request 

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

View in API Explorer →

Example Object 

{
  "type": "Group",
  "id": "1",
  "attributes": {
    "archived_at": "2000-01-01T12:00:00Z",
    "can_create_conversation": true,
    "can_create_conversation_reason_code": "string",
    "chat_enabled": true,
    "contact_email": "string",
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "description_as_plain_text": "string",
    "events_listed": true,
    "events_visibility": "value",
    "header_image": {},
    "leaders_can_search_people_database": true,
    "listed": true,
    "location_type_preference": "value",
    "members_are_confidential": true,
    "memberships_count": 1,
    "name": "string",
    "public_church_center_web_url": "string",
    "schedule": "string",
    "tag_ids": 1,
    "virtual_location_url": "string",
    "widget_status": {}
  },
  "relationships": {
    "group_type": {
      "data": {
        "type": "GroupType",
        "id": "1"
      }
    },
    "location": {
      "data": {
        "type": "Location",
        "id": "1"
      }
    }
  }
}

Attributes

Name Type Description
archived_at date_time

The date and time the group was archived.
can_create_conversation boolean

A boolean representing the current user's authorization to start a new conversation in the group.

Only available when requested with the ?fields param
can_create_conversation_reason_code string

A code representing why the current user can or cannot start a new conversation in the group. Possible values: chat_disabled, group_archived, non_member, leaders_only. Nil when the user is permitted to create a conversation.

Only available when requested with the ?fields param
chat_enabled boolean

A boolean representing whether or not the group has Chat enabled.
contact_email string

If a contact_email is provided, we will display a contact button on the public page where potential members can ask questions before joining the group.
created_at date_time

The date and time the group was created.
description string

A longform description of the group. Can contain HTML markup.
description_as_plain_text string

The plain text version of the group description.
events_listed boolean

Whether or not events are visible to the public on Church Center
events_visibility string

The visibility of events for the group.

Possible values: public or members
header_image hash

A hash of header image URLs. The keys are thumbnail, medium, and original.

{
  "thumbnail": "https://groups-production.s3.amazonaws.com/uploads/group/header_image/1986065/thumbnail_image-1676676396838.jpg",
  "medium": "https://groups-production.s3.amazonaws.com/uploads/group/header_image/1986065/medium_image-1676676396838.jpg",
  "original": "https://groups-production.s3.amazonaws.com/uploads/group/header_image/1986065/image-1676676396838.jpg"
}
id primary_key
leaders_can_search_people_database boolean

Whether or not group leaders have access to the entire church database on the admin side of Groups. (Not recommended)
listed boolean

Whether or not the group is visible on Church Center
location_type_preference string

The location type preference for the group.

Possible values: physical or virtual
members_are_confidential boolean

Whether or not group members can see other members' info
memberships_count integer

The number of members in the group, includes leaders. Does not include membership requests.
name string

The name/title of the group.
public_church_center_web_url string

The public URL for the group on Church Center.
schedule string

A text summary of the group's typical meeting schedule. Can be a string like "Sundays at 9:30am" or "Every other Tuesday at 7pm".
tag_ids integer

The IDs of the tags associated with the group.

Only available when requested with the ?fields param
virtual_location_url string

The URL for the group's virtual location. A zoom link, for example. This could be set even if location_type_preference is physical. This is useful if you want to display a zoom link even if the group is meeting in person.
widget_status hash

DEPRECATED: This is a private attribute used by Home widgets that we plan to remove soon.

Only available when requested with the ?fields param

Relationships

Name Type Association Type Note
group_type GroupType to_one

The group type that this group belongs to. Unique groups do not belong to a group type and will return a null data set for the relationship.
location Location to_one

The group's default location is where the group normally meets. But remember, each group event can have its own location if needed.

Can Include

Parameter Value Description Assignable
include enrollment

include associated enrollment
include group_type

include associated group_type

 create and update
include location

include associated location

 create and update

Order By

Parameter Value Type Description
order chat_enabled string

prefix with a hyphen (-chat_enabled) to reverse the order
order contact_email string

prefix with a hyphen (-contact_email) to reverse the order
order created_at string

prefix with a hyphen (-created_at) to reverse the order
order enrollment_limit string

prefix with a hyphen (-enrollment_limit) to reverse the order
order listed string

prefix with a hyphen (-listed) to reverse the order
order members_are_confidential string

prefix with a hyphen (-membersareconfidential) to reverse the order
order memberships_count string

prefix with a hyphen (-memberships_count) to reverse the order
order name string

prefix with a hyphen (-name) to reverse the order

Query By

Name Parameter Type Description Example
archive_status where[archive_status] string

Query on a specific archive_status

Possible values: not_archived, only, or include

 ?where[archive_status]=value
name where[name] string

Query on a specific name

 ?where[name]=string

Pagination

Name Parameter Type Description
per_page per_page integer

how many records to return per page (min=1, max=100, default=25)
offset offset integer

get results from given offset

Endpoints

Listing

HTTP Method Endpoint
GET /groups/v2/groups

Reading

HTTP Method Endpoint
GET /groups/v2/groups/{id}

Updating

HTTP Method Endpoint Assignable Attributes
PATCH /groups/v2/groups/{id}
  • name
  • group_type_id
  • schedule
  • tag_ids

Actions

HTTP Method Endpoint Description
POST https://api.planningcenteronline.com/groups/v2/groups/{group_id}/assign_campuses
POST https://api.planningcenteronline.com/groups/v2/groups/{group_id}/disable_chat
POST https://api.planningcenteronline.com/groups/v2/groups/{group_id}/duplicate
POST https://api.planningcenteronline.com/groups/v2/groups/{group_id}/enable_chat

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/applications GroupApplication

requests to join this group
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/campuses Campus

campuses assigned this group
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/enrollment Enrollment

enrollment details for this group
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/events Event

events for this group
  • canceled

    have a canceled_at date and time

  • not_canceled

    do not have a canceled_at date and time
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/group_type GroupType

group type of this group
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/location Location

default physical location for this group's events
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/memberships Membership

memberships belonging to this group
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/my_membership Membership

the current person's membership for this group
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/people Person

people who have memberships for this group
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/resources Resource

file and link resources shared with this group
  • leaders

    only visible to group leaders
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/tags Tag

tags assigned to this group

Belongs To

HTTP Method Endpoint Association Details Filter By
GET https://api.planningcenteronline.com/groups/v2/campuses/{campus_id}/groups Campus

groups which have applied this campus
GET https://api.planningcenteronline.com/groups/v2/events/{event_id}/group Event

group which the event belongs to
GET https://api.planningcenteronline.com/groups/v2/group_applications/{group_application_id}/group GroupApplication

group being applied to
GET https://api.planningcenteronline.com/groups/v2/group_types/{group_type_id}/groups GroupType

groups belonging to this group type
GET https://api.planningcenteronline.com/groups/v2/events/{event_id}/location/{location_id}/group Location

group that manages this location
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/memberships/{membership_id}/group Membership

group for this membership
GET https://api.planningcenteronline.com/groups/v2/groups Organization

groups for this organization
  • campus

    from specific campuses; provide an additional campus_id param as a comma-separated list of IDs, ex: ?filter=campus&campus_id=1,2,3

  • enrollment

    filter groups with enrollment settings; provide an additional enrollment param as a comma-separated list of values, ex: ?filter=enrollment&enrollment=open_signup,request_to_join,closed

  • group

    from specific groups; provide an additional group_id param as a comma-separated list of IDs, ex: ?filter=group&group_id=1,2,3

  • group_type

    from specific group types; provide an additional group_type_id param as a comma-separated list of IDs, ex: ?filter=group_type&group_type_id=1,2,3

  • hidden

    filter groups that are not published on Church Center

  • meeting_schedule

    filter groups that have a meeting schedule

  • my_groups

    only groups of which you are a member

  • people_database_searchable

    based on their setting of allowing leaders to search the entire church database in Groups; provide an additional people_database_searchable param with only or none, ex: ?filter=people_database_searchable&people_database_searchable=only

  • published

    filter groups that are published on Church Center

  • tag

    filter groups with tags; provide an additional tag_id param as a comma-separated list of IDs, ex: ?filter=tag&tag_id=1,2,3. filtering by tags within a tag group will expand results, and across tag groups will reduce results.
GET https://api.planningcenteronline.com/groups/v2/people/{person_id}/groups Person

groups of which this person is a member
GET https://api.planningcenteronline.com/groups/v2/groups/{group_id}/tags/{tag_id}/groups Tag

groups which have applied this tag