Person - Services API - Planning Center

Example Request

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

View in API Explorer →

Example Object

{
  "type": "Person",
  "id": "1",
  "attributes": {
    "access_media_attachments": true,
    "access_plan_attachments": true,
    "access_song_attachments": true,
    "anniversary": "2000-01-01T12:00:00Z",
    "archived": true,
    "archived_at": "2000-01-01T12:00:00Z",
    "assigned_to_rehearsal_team": true,
    "birthdate": "2000-01-01T12:00:00Z",
    "can_edit_all_people": true,
    "can_view_all_people": true,
    "created_at": "2000-01-01T12:00:00Z",
    "facebook_id": "primary_key",
    "first_name": "string",
    "full_name": "string",
    "given_name": "string",
    "ical_code": "string",
    "last_name": "string",
    "legacy_id": "primary_key",
    "logged_in_at": "2000-01-01T12:00:00Z",
    "max_permissions": "string",
    "max_plan_permissions": "string",
    "me_tab": "string",
    "media_permissions": "string",
    "media_tab": "string",
    "middle_name": "string",
    "name_prefix": "string",
    "name_suffix": "string",
    "nickname": "string",
    "notes": "string",
    "onboardings": [],
    "passed_background_check": true,
    "people_tab": "string",
    "permissions": "string",
    "photo_thumbnail_url": "string",
    "photo_url": "string",
    "plans_tab": "string",
    "praise_charts_enabled": true,
    "preferred_app": "string",
    "preferred_max_plans_per_day": 1,
    "preferred_max_plans_per_month": 1,
    "profile_name": "string",
    "signature": "string",
    "site_administrator": true,
    "song_permissions": "string",
    "songs_tab": "string",
    "status": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "created_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "updated_by": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "current_folder": {
      "data": {
        "type": "Folder",
        "id": "1"
      }
    }
  }
}

Attributes

Name	Type	Description
`access_media_attachments`	`boolean`
`access_plan_attachments`	`boolean`
`access_song_attachments`	`boolean`
`anniversary`	`date_time`
`archived`	`boolean`
`archived_at`	`date_time`
`assigned_to_rehearsal_team`	`boolean`
`birthdate`	`date_time`
`can_edit_all_people`	`boolean`
`can_view_all_people`	`boolean`
`created_at`	`date_time`
`facebook_id`	`primary_key`	DEPRECATED: this attribute will be removed in the next release and will return the string "DEPRECATED" in this version
`first_name`	`string`
`full_name`	`string`
`given_name`	`string`
`ical_code`	`string`
`id`	`primary_key`
`last_name`	`string`
`legacy_id`	`primary_key`	If you've used Person.id from API v1 this attribute can be used to map from those old IDs to the new IDs used in API v2
`logged_in_at`	`date_time`
`max_permissions`	`string`
`max_plan_permissions`	`string`
`me_tab`	`string`
`media_permissions`	`string`
`media_tab`	`string`
`middle_name`	`string`
`name_prefix`	`string`
`name_suffix`	`string`
`nickname`	`string`
`notes`	`string`
`onboardings`	`array`
`passed_background_check`	`boolean`
`people_tab`	`string`
`permissions`	`string`
`photo_thumbnail_url`	`string`
`photo_url`	`string`
`plans_tab`	`string`
`praise_charts_enabled`	`boolean`
`preferred_app`	`string`
`preferred_max_plans_per_day`	`integer`
`preferred_max_plans_per_month`	`integer`
`profile_name`	`string`	Only available when requested with the `?fields` param
`signature`	`string`	Only available when requested with the `?fields` param
`site_administrator`	`boolean`
`song_permissions`	`string`
`songs_tab`	`string`
`status`	`string`
`updated_at`	`date_time`

Relationships

Name	Type	Association Type
created_by	Person	to_one
updated_by	Person	to_one
current_folder	Folder	to_one

Can Include

Parameter	Value	Description
include	emails	include associated emails
include	tags	include associated tags
include	team_leaders	include associated team_leaders

Order By

Parameter	Value	Type	Description
order	created_at	string	prefix with a hyphen (-created_at) to reverse the order
order	first_name	string	prefix with a hyphen (-first_name) to reverse the order
order	last_name	string	prefix with a hyphen (-last_name) 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
assigned_to_rehearsal_team	`where[assigned_to_rehearsal_team]`	boolean	Query on a specific assignedtorehearsal_team	`?where[assigned_to_rehearsal_team]=true`
legacy_id	`where[legacy_id]`	primary_key	Query on a specific legacy_id	`?where[legacy_id]=primary_key`

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	`/services/v2/people`

Reading

HTTP Method	Endpoint
GET	`/services/v2/people/{id}`

Updating

HTTP Method	Endpoint	Assignable Attributes
PATCH	`/services/v2/people/{id}`	preferred_app onboardings access_media_attachments access_plan_attachments access_song_attachments current_folder_id media_permissions permissions song_permissions

Actions

HTTP Method	Endpoint	Description
POST	`https://api.planningcenteronline.com/services/v2/people/{person_id}/assign_tags`	Used to assign tags to a person.
POST	`https://api.planningcenteronline.com/services/v2/people/{person_id}/collapse_service_types`	Used to set Service Types as collapsed for the Person
POST	`https://api.planningcenteronline.com/services/v2/people/{person_id}/expand_service_types`	Used to set Service Types as expanded for the Person

Associations

HTTP Method	Endpoint	Returns	Filter By
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/available_signups`	AvailableSignup	`current_organization`
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/blockouts`	Blockout	`future` `past`
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/emails`	Email
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/person_team_position_assignments`	PersonTeamPositionAssignment	`not_archived` `not_deleted`
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/plan_people`	PlanPerson
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules`	Schedule	`after` Fetch schedules after the included `after` iso8601 date param. e.g. `?filter=after&after=2020-01-01T00:00:00Z` `all` `before` Fetch schedules before the included `before` iso8601 date param. e.g. `?filter=before&before=2020-01-01T00:00:00Z` `future` `not_across_organizations` `past` `with_declined`
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/scheduling_preferences`	SchedulingPreference
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/tags`	Tag
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/team_leaders`	TeamLeader	`not_archived` `not_deleted`
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/text_settings`	TextSetting

Belongs To

HTTP Method	Endpoint	Association
GET	`https://api.planningcenteronline.com/services/v2/series/{series_id}/plans/{plan_id}/live/{live_id}/controller`	Live
GET	`https://api.planningcenteronline.com/services/v2/people`	Organization
GET	`https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/team_positions/{team_position_id}/person_team_position_assignments/{person_team_position_assignment_id}/person`	PersonTeamPositionAssignment
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/plan_people/{plan_person_id}/person`	PlanPerson
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules/{schedule_id}/respond_to`	Schedule
GET	`https://api.planningcenteronline.com/services/v2/people/{person_id}/team_leaders/{team_leader_id}/people`	TeamLeader
GET	`https://api.planningcenteronline.com/services/v2/teams/{team_id}/people`	Team