My Developer Account

Schedule

An instance of a PlanPerson with included data for displaying in a user's schedule

Example Request 

curl https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules

View in API Explorer →

Example Object 

{
  "type": "Schedule",
  "id": "1",
  "attributes": {
    "can_accept_partial": true,
    "can_accept_partial_one_time": true,
    "can_rehearse": true,
    "dates": "string",
    "decline_reason": "string",
    "organization_name": "string",
    "organization_time_zone": "string",
    "organization_twenty_four_hour_time": "string",
    "person_name": "string",
    "plan_visible": true,
    "plan_visible_to_me": true,
    "position_display_times": "string",
    "reschedule_declines": "string",
    "responds_to_name": "string",
    "service_type_name": "string",
    "short_dates": "string",
    "sort_date": "2000-01-01T12:00:00Z",
    "status": "string",
    "team_name": "string",
    "team_position_name": "string"
  },
  "relationships": {
    "person": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "service_type": {
      "data": {
        "type": "ServiceType",
        "id": "1"
      }
    },
    "organization": {
      "data": {
        "type": "Organization",
        "id": "1"
      }
    },
    "plan_person": {
      "data": {
        "type": "PlanPerson",
        "id": "1"
      }
    },
    "plan": {
      "data": {
        "type": "Plan",
        "id": "1"
      }
    },
    "team": {
      "data": {
        "type": "Team",
        "id": "1"
      }
    },
    "responds_to_person": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "times": {
      "data": [
        {
          "type": "PlanTime",
          "id": "1"
        }
      ]
    }
  }
}

Attributes

Name Type Description
can_accept_partial boolean
can_accept_partial_one_time boolean
can_rehearse boolean
dates string
decline_reason string
id primary_key
organization_name string
organization_time_zone string
organization_twenty_four_hour_time string
person_name string
plan_visible boolean

True if the scheduled Plan is visible to the scheduled Person
plan_visible_to_me boolean

True if the scheduled Plan is visible to the current Person
position_display_times string
reschedule_declines string
responds_to_name string
service_type_name string
short_dates string
sort_date date_time
status string
team_name string
team_position_name string

Relationships

Name Type Association Type Note
person Person to_one
service_type ServiceType to_one
organization Organization to_one
plan_person PlanPerson to_one
plan Plan to_one
team Team to_one
responds_to_person Person to_one
times PlanTime to_many

Can Include

Parameter Value Description Assignable
include plan_times

include associated plan_times

Order By

Parameter Value Type Description
order starts_at string

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

Query By

Name Parameter Type Description Example
plan_id where[plan_id] integer

Query on a related plan

 ?where[plan_id]=1

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/{person_id}/schedules

Reading

HTTP Method Endpoint
GET /services/v2/people/{person_id}/schedules/{id}

Actions

HTTP Method Endpoint Description
POST https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules/{schedule_id}/accept

Accept a Schedule

If this isn't a split time schedule, or you want to accept all times, an empty JSON body is accepted.

If the user wants to decline specific times you'll need to send the declined time IDs & a reason.

A POST body should be formated...

{
  "data": {
    "type": "ScheduleAccept",
    "attributes": {
      "reason": "Because reasons"
    },
    "relationships": {
      "declined_plan_times": {
        "data": [
          {
            "type": "PlanTime",
            "id": "1"
          }
        ]
      }
    }
  }
}

Proposing a replacement

When every time is declined the request falls through to the decline flow, and the optional replacement_id and replacement_confirmed attributes may be included. When the team is configured to reschedule declines with a volunteer replacement and replacement_id is present, the decline initiates the replacement workflow (contacting the chosen person). replacement_confirmed indicates whether the replacement has already agreed to fill in — skipping the confirmation step when true.

replacement_id is the account_center_id of the proposed replacement.

{
  "data": {
    "type": "ScheduleAccept",
    "attributes": {
      "reason": "Because reasons",
      "replacement_id": "123",
      "replacement_confirmed": true
    },
    "relationships": {
      "declined_plan_times": {
        "data": [
          {
            "type": "PlanTime",
            "id": "1"
          }
        ]
      }
    }
  }
}

Note: replacement_id is not validated against a list of eligible replacements; any person in the organization may be submitted. The calling UI is responsible for presenting an appropriate list, matching the existing volunteer-chooses-their-own-replacement flow.
POST https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules/{schedule_id}/decline

Decline a Schedule

If this is a split time request, all times will be declined.

If you want to decline specific times see ScheduleAcceptAction.

A POST body should be formated...

{
  "data": {
    "type": "ScheduleDecline",
    "attributes": {
      "reason": "A user supplied reason for declining the request or an empty string."
    },
    "relationships": null
  }
}

Proposing a replacement

The optional replacement_id and replacement_confirmed attributes may be included on a decline. When the team is configured to reschedule declines with a volunteer replacement and replacement_id is present, the decline initiates the replacement workflow (contacting the chosen person). replacement_confirmed indicates whether the replacement has already agreed to fill in — skipping the confirmation step when true.

replacement_id is the account_center_id of the proposed replacement.

{
  "data": {
    "type": "ScheduleDecline",
    "attributes": {
      "reason": "A user supplied reason for declining the request or an empty string.",
      "replacement_id": "123",
      "replacement_confirmed": true
    },
    "relationships": null
  }
}

Note: replacement_id is not validated against a list of eligible replacements; any person in the organization may be submitted. The calling UI is responsible for presenting an appropriate list, matching the existing volunteer-chooses-their-own-replacement flow.

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules/{schedule_id}/declined_plan_times PlanTime
GET https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules/{schedule_id}/plan_times PlanTime
GET https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules/{schedule_id}/respond_to Person
GET https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules/{schedule_id}/team Team

Belongs To

HTTP Method Endpoint Association Details Filter By
GET https://api.planningcenteronline.com/services/v2/people/{person_id}/schedules Person
  • 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/service_types/{service_type_id}/plans/{plan_id}/my_schedules Plan