A list is a powerful tool for finding and grouping people together using any criteria imaginable.
| Property | Value |
|---|---|
| Product | People (pco.people, API version 2026-10-05) |
| Resource type | List |
| TypeScript | People.List, attributes People.ListAttributes, schema People.ListSchema |
| Planning Center path | /people/v2/lists |
| Planning Center docs | List |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.people.lists |
Collection | auto_refresh_enabled, can_manage, has_active_automations, mailchimp_connected, needs_attention, recently_viewed, starred, unassigned |
No |
pco.people.campuses.id(campusId).lists |
Collection | No | |
pco.people.list_categories.id(listCategoryId).lists |
Collection | No |
From a collection, .id(listId) addresses one List: pco.people.lists.id(listId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On People.ListAttributes. Every resource also has id and type ('List') next to its attributes.
| Name | Type | Description |
|---|---|---|
active_automations_count |
number | null |
|
auto_generated_name |
boolean | null |
|
auto_refresh |
boolean | null |
|
auto_refresh_frequency |
string | null |
|
automations_active |
boolean | null |
|
automations_count |
number | null |
|
batch_completed_at |
string | null |
|
created_at |
string | null |
|
description |
string | null |
|
has_inactive_results |
boolean | null |
|
include_inactive |
boolean | null |
|
invalid |
boolean | null |
|
name |
string | null |
|
name_or_description |
string | null |
|
paused_automations_count |
number | null |
|
recently_viewed |
boolean | null |
|
refreshed_at |
string | null |
|
return_original_if_none |
boolean | null |
|
returns |
string | null |
|
starred |
boolean | null |
|
status |
string | null |
|
subset |
string | null |
|
total_people |
number | null |
|
updated_at |
string | null |
Relationships and includes
Side-load with include() (or get({ include })) and read with related(resource, name): campus, category, created_by, mailchimp_sync_status, people, rules, shares, updated_by.
Querying
Where
where(field, value) for equality; where(field, op, value) with the operators listed.
| Field | Value type | Operators |
|---|---|---|
batch_completed_at |
string | Date |
gt, gte, lt, lte |
created_at |
string | Date |
gt, gte, lt, lte |
id |
string |
Equality only |
name |
string |
Equality only |
updated_at |
string | Date |
gt, gte, lt, lte |
Order
order(...) accepts these fields, ascending, or descending with a - prefix: active_automations_count, auto_refresh_frequency, automations_count, batch_completed_at, campus_id, campuses.name, created_at, list_categories.name, list_category_id, name, name_or_description, refreshed_at, starred, total_people, updated_at.
Filters
filter(...) names depend on the edge you query through:
| Edge | Filters |
|---|---|
pco.people.lists |
auto_refresh_enabled, can_manage, has_active_automations, mailchimp_connected, needs_attention, recently_viewed, starred, unassigned |
Edges
Follow these from one List, ref = pco.people.lists.id(listId):
| Edge | Leads to | Returns | Filters | Create |
|---|---|---|---|---|
ref.campus |
Campus | Collection | No | |
ref.category |
ListCategory | Collection | No | |
ref.created_by |
Person | Collection | No | |
ref.list_results |
ListResult | Collection | No | |
ref.mailchimp_sync_status |
MailchimpSyncStatus | Collection | No | |
ref.people |
Person | Collection | No | |
ref.rules |
Rule | Collection | No | |
ref.shares |
ListShare | Collection | Yes | |
ref.star |
ListStar | Single resource | Yes | |
ref.updated_by |
Person | Collection | No |
Writing
| Property | Value |
|---|---|
| Create | No |
| Update | Yes, update() on a reference |
| Delete | No |
Update attributes
Typed as People.ListSchema['update'].
| Attribute | Type |
|---|---|
campus_id |
string |
list_category_id |
string |
See Writing data.
Actions
Run with ref.action(name, body?). Bodies are untyped: see Planning Center’s docs for each action.
| Action | Path | Description |
|---|---|---|
mailchimp_sync |
POST /people/v2/lists/{list_id}/mailchimp_sync |
Sync a List to Mailchimp. (Mailchimp integration must already be configured for this organization.) |
run |
POST /people/v2/lists/{list_id}/run |
Run a List to update its results. |
Example
import type { People } from '@mackenly/planningcenterkit';
const page = await pco.people.lists.order('active_automations_count').perPage(25).list();
const items: People.List[] = page.data;