Skip to content

List (People)

A list is a powerful tool for finding and grouping people together using any criteria imaginable.

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;

Type to search…

↑↓ navigate↵ selectEsc close