API
⌘K
My Developer Account

Person

A person added to Planning Center Services.

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 Note
created_by Person to_one
updated_by Person to_one
current_folder Folder to_one

Can Include

Parameter Value Description Assignable
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 assigned_to_rehearsal_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 Details 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
  • all
  • before
  • 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 Details Filter By
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