Appointment Groups API

API for creating, accessing and updating appointment groups. Appointment groups provide a way of creating a bundle of time slots that users can sign up for (e.g. "Office Hours" or "Meet with professor about Final Project"). Both time slots and reservations of time slots are stored as Calendar Events.

An Appointment Group object looks like:

{
  // The ID of the appointment group
  id: 543,

  // The title of the appointment group
  title: "Final Presentation",

  // The start of the first time slot in the appointment group
  start_at: "2012-07-20T15:00:00-06:00",

  // The end of the last time slot in the appointment group
  end_at: "2012-07-20T17:00:00-06:00",

  // The text description of the appointment group
  description: "Es muy importante",

  // The location name of the appointment group
  location_name: "El Tigre Chino's office",

  // The address of the appointment group's location
  location_address: "Room 234",

  // The number of participant who have reserved slots
  // (see include[] argument)
  participant_count: 2,

  // The start and end times of slots reserved by the current user as
  // well as the id of the calendar event for the reservation (see
  // include[] argument)
  reserved_times: [{id: 987,
                    start_at: "2012-07-20T15:00:00-06:00",
                    start_at: "2012-07-20T15:00:00-06:00"}],

  // The context codes (i.e. courses) this appointment group belongs to.
  // Only people in these courses will be eligible to sign up.
  context_codes: ["course_123"],

  // The sub-context codes (i.e. course sections and group categories)
  // this appointment group is restricted to
  sub_context_codes: ["course_section_234"],

  // Current state of the appointment group ("pending", "active" or
  // "deleted"). "pending" indicates that it has not been published yet
  // and is invisible to participants.
  workflow_state: "active",

  // Boolean indicating whether the current user needs to sign up for
  // this appointment group (i.e. it's reservable and the
  // min_appointments_per_participant limit has not been met by this
  // user).
  requiring_action: true,

  // Number of time slots in this appointment group
  appointments_count: 2,

  // Calendar Events representing the time slots (see include[] argument)
  // Refer to the Calendar Events API for more information
  appointments: [ ... ],

  // Newly created time slots (same format as appointments above). Only
  // returned in Create/Update responses where new time slots have been
  // added
  new_appointments: [ ... ],

  // Maximum number of time slots a user may register for, or null if no
  // limit
  max_appointments_per_participant: 1,

  // Minimum number of time slots a user must register for. If not set,
  // users do not need to sign up for any time slots
  min_appointments_per_participant: 1,

  // Maximum number of participants that may register for each time slot,
  // or null if no limit
  participants_per_appointment: 1,

  // "private" means participants cannot see who has signed up for a
  // particular time slot, "protected" means that they can
  participant_visibility: "private",

  // Indicates how participants sign up for the appointment group, either
  // as individuals ("User") or in student groups ("Group"). Related to 
  // sub_context_codes (i.e. "Group" signups always have a single group
  // category)
  participant_type: "User",

  // URL for this appointment group (to update, delete, etc.)
  url: "https://example.com/api/v1/appointment_groups/543",

  // URL for a user to view this appointment group
  html_url: "http://example.com/appointment_groups/1",

  // When the appointment group was created
  created_at: "2012-07-13T10:55:20-06:00",

  // When the appointment group was last updated
  updated_at: "2012-07-13T10:55:20-06:00"
}

List appointment groups AppointmentGroupsController#index

GET /api/v1/appointment_groups

Retrieve the list of appointment groups that can be reserved or managed by the current user.

Request Parameters:

scope
Optional, "reservable"|"manageable"

Defaults to "reservable"
context_codes[]
Optional

Array of context codes used to limit returned results.
include_past_appointments
Optional

Boolean, defaults to false.

If true, includes past appointment groups
include[]
Optional

Array of additional information to include.

Allowable values include "appointments" (i.e. calendar event time slots for this appointment group), "child_events" (i.e. reservations of those time slots), "participant_count" (i.e. number of reservations), and "reserved_times" (i.e. the event id, start time and end time of reservations the current user has made)

Create an appointment group AppointmentGroupsController#create

POST /api/v1/appointment_groups

Create and return a new appointment group. If new_appointments are specified, the response will return a new_appointments array (same format as appointments array, see "List appointment groups" action)

Request Parameters:

appointment_group[context_codes][]
Required

Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group.
appointment_group[sub_context_codes][]
Optional

Array of sub context codes (course sections or a single group category) this group should be linked to. Used to limit the appointment group to particular sections. If a group category is specified, students will sign up in groups and the participant_type will be "Group" instead of "User".
appointment_group[title]
Optional

Short title for the appointment group.
appointment_group[description]
Optional

Longer text description of the appointment group.
appointment_group[location_name]
Optional

Location name of the appointment group.
appointment_group[location_address]
Optional

Location address.
appointment_group[publish]
Optional

Boolean, default false. Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished.
appointment_group[participants_per_appointment]
Optional

Maximum number of participants that may register for each time slot. Defaults to null (no limit).
appointment_group[min_appointments_per_participant]
Optional

Minimum number of time slots a user must register for. If not set, users do not need to sign up for any time slots.
appointment_group[max_appointments_per_participant]
Optional

Maximum number of time slots a user may register for.
appointment_group[new_appointments][X][]
Optional

Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request.
appointment_group[participant_visibility]
Optional, "private"|"protected"

"private" means participants cannot see who has signed up for a particular time slot, "protected" means that they can. Defaults to "private".

Example Request:

curl 'http://<canvas>/api/v1/appointment_groups.json' \ 
     -X POST \ 
     -F 'appointment_group[context_codes][]=course_123' \ 
     -F 'appointment_group[sub_context_codes][]=course_section_234' \ 
     -F 'appointment_group[title]=Final Presentation' \ 
     -F 'appointment_group[participants_per_appointment]=1' \
     -F 'appointment_group[min_appointments_per_participant]=1' \
     -F 'appointment_group[max_appointments_per_participant]=1' \
     -F 'appointment_group[new_appointments][0][]=2012-07-19T21:00:00Z' \ 
     -F 'appointment_group[new_appointments][0][]=2012-07-19T22:00:00Z' \ 
     -F 'appointment_group[new_appointments][1][]=2012-07-19T22:00:00Z' \ 
     -F 'appointment_group[new_appointments][1][]=2012-07-19T23:00:00Z' \ 
     -H "Authorization: Bearer <token>"

Get a single appointment group AppointmentGroupsController#show

GET /api/v1/appointment_groups/:id

Returns information for a single appointment group

Request Parameters:

include[]
Optional

Array of additional information to include.

Allowable values include "child_events" (i.e. reservations of time slots time slots). "appointments" will always be returned (see include[] argument of "List appointment groups" action).

Update an appointment group AppointmentGroupsController#update

PUT /api/v1/appointment_groups/:id

Update and return an appointment group. If new_appointments are specified, the response will return a new_appointments array (same format as appointments array, see "List appointment groups" action).

Request Parameters:

appointment_group[context_codes][]
Optional

Array of context codes to add to this appointment group (existing ones cannot be removed).
appointment_group[sub_context_codes][]
Optional

Array of sub context codes to add to this appointment group (existing ones cannot be removed).
appointment_group[title]
Optional

Short title for the appointment group.
appointment_group[description]
Optional

Longer text description of the appointment group.
appointment_group[location_name]
Optional

Location name of the appointment group.
appointment_group[location_address]
Optional

Location address.
appointment_group[publish]
Optional

Boolean, default false. Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished.
appointment_group[participants_per_appointment]
Optional

Maximum number of participants that may register for each time slot. Defaults to null (no limit). Changes will not affect existing reservations.
appointment_group[min_appointments_per_participant]
Optional

Minimum number of time slots a user must register for. If not set, users do not need to sign up for any time slots. Changes will not affect existing reservations.
appointment_group[max_appointments_per_participant]
Optional

Maximum number of time slots a user may register for. Changes will not affect existing reservations.
appointment_group[new_appointments][X][]
Optional

Nested array of new start time/end time pairs indicating time slots for this appointment group. Refer to the example request. To remove existing time slots or reservations, use the Calendar Event API.
appointment_group[participant_visibility]
Optional, "private"|"protected"

"private" means participants cannot see who has signed up for a particular time slot, "protected" means that they can.

Example Request:

curl 'http://<canvas>/api/v1/appointment_groups/543.json' \ 
     -X PUT \ 
     -F 'appointment_group[publish]=1' \
     -H "Authorization: Bearer <token>"

Delete an appointment group AppointmentGroupsController#destroy

DELETE /api/v1/appointment_groups/:id

Delete an appointment group (and associated time slots and reservations) and return the deleted group

appointment group.

Request Parameters:

cancel_reason
Optional

Reason for deleting/canceling the

Example Request:

curl 'http://<canvas>/api/v1/appointment_groups/543.json' \ 
     -X DELETE \ 
     -F 'cancel_reason=El Tigre Chino got fired' \ 
     -H "Authorization: Bearer <token>"

List user participants AppointmentGroupsController#users

GET /api/v1/appointment_groups/:id/users

List users that are (or may be) participating in this appointment group. Refer to the Users API for the response fields. Returns no results for appointment groups with the "Group" participant_type.

Request Parameters:

registration_status
Optional, "all"|"registered"|"registered"

Limits results to the a given participation status, defaults to "all"

List student group participants AppointmentGroupsController#groups

GET /api/v1/appointment_groups/:id/groups

List student groups that are (or may be) participating in this appointment group. Refer to the Groups API for the response fields. Returns no results for appointment groups with the "User" participant_type.

Request Parameters:

registration_status
Optional, "all"|"registered"|"registered"

Limits results to the a given participation status, defaults to "all"