API
⌘K
My Developer Account

List

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

Example Request 

curl https://api.planningcenteronline.com/people/v2/lists

View in API Explorer →

Example Object 

{
  "type": "List",
  "id": "1",
  "attributes": {
    "active_automations_count": 1,
    "auto_generated_name": true,
    "auto_refresh": true,
    "auto_refresh_frequency": "string",
    "automations_active": true,
    "automations_count": 1,
    "batch_completed_at": "2000-01-01T12:00:00Z",
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "has_inactive_results": true,
    "include_inactive": true,
    "invalid": true,
    "name": "string",
    "name_or_description": "string",
    "paused_automations_count": 1,
    "recently_viewed": true,
    "refreshed_at": "2000-01-01T12:00:00Z",
    "return_original_if_none": true,
    "returns": "string",
    "starred": true,
    "status": "string",
    "subset": "string",
    "total_people": 1,
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}

Attributes

Name Type Description
active_automations_count integer
auto_generated_name boolean
auto_refresh boolean
auto_refresh_frequency string
automations_active boolean
automations_count integer
batch_completed_at date_time
created_at date_time
description string
has_inactive_results boolean
id primary_key
include_inactive boolean
invalid boolean
name string
name_or_description string
paused_automations_count integer
recently_viewed boolean
refreshed_at date_time
return_original_if_none boolean
returns string
starred boolean
status string
subset string
total_people integer
updated_at date_time

Can Include

Parameter Value Description Assignable
include campus

include associated campus

 create and update
include category

include associated category
include created_by

include associated created_by
include mailchimp_sync_status

include associated mailchimpsyncstatus
include people

include associated people
include rules

include associated rules
include shares

include associated shares
include updated_by

include associated updated_by

Order By

Parameter Value Type Description
order active_automations_count string

prefix with a hyphen (-activeautomationscount) to reverse the order
order auto_refresh_frequency string

prefix with a hyphen (-autorefreshfrequency) to reverse the order
order automations_count string

prefix with a hyphen (-automations_count) to reverse the order
order batch_completed_at string

prefix with a hyphen (-batchcompletedat) to reverse the order
order campus_id string

prefix with a hyphen (-campus_id) to reverse the order
order campuses.name string

prefix with a hyphen (-campuses.name) to reverse the order
order created_at string

prefix with a hyphen (-created_at) to reverse the order
order list_categories.name string

prefix with a hyphen (-list_categories.name) to reverse the order
order list_category_id string

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

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

prefix with a hyphen (-nameordescription) to reverse the order
order refreshed_at string

prefix with a hyphen (-refreshed_at) to reverse the order
order starred string

prefix with a hyphen (-starred) to reverse the order
order total_people string

prefix with a hyphen (-total_people) to reverse the order
order updated_at string

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

Query By

Name Parameter Type Description Example
batch_completed_at where[batch_completed_at] date_time

Query on a specific batchcompletedat

 ?where[batch_completed_at]=2000-01-01T12:00:00Z
created_at where[created_at] date_time

Query on a specific created_at

 ?where[created_at]=2000-01-01T12:00:00Z
id where[id] primary_key

Query on a specific id

 ?where[id]=primary_key
name where[name] string

Query on a specific name

 ?where[name]=string
updated_at where[updated_at] date_time

Query on a specific updated_at

 ?where[updated_at]=2000-01-01T12:00:00Z

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 /people/v2/lists

Reading

HTTP Method Endpoint
GET /people/v2/lists/{id}

Updating

HTTP Method Endpoint
PATCH /people/v2/lists/{id}

Actions

HTTP Method Endpoint Description
POST https://api.planningcenteronline.com/people/v2/lists/{list_id}/mailchimp_sync

Sync a List to Mailchimp. (Mailchimp integration must already be configured for this organization.)
POST https://api.planningcenteronline.com/people/v2/lists/{list_id}/run

Run a List to update its results.

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/campus Campus
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/category ListCategory
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/created_by Person
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/list_results ListResult
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/mailchimp_sync_status MailchimpSyncStatus
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/people Person
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/rules Rule
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/shares ListShare
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/star ListStar
GET https://api.planningcenteronline.com/people/v2/lists/{list_id}/updated_by Person

Belongs To

HTTP Method Endpoint Association Details Filter By
GET https://api.planningcenteronline.com/people/v2/campuses/{campus_id}/lists Campus
GET https://api.planningcenteronline.com/people/v2/list_categories/{list_category_id}/lists ListCategory
GET https://api.planningcenteronline.com/people/v2/lists Organization
  • auto_refresh_enabled
  • can_manage
  • has_active_automations
  • mailchimp_connected
  • needs_attention
  • recently_viewed
  • starred
  • unassigned