Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • API Reference
        • Captions
        • Collection
        • Courses
        • Group
        • Insights
        • Media
        • Media Upload
        • Ping
        • Professional Captioning
        • Tags
        • Transfer Media
        • User
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page
  • List appointment groups
  • Create an appointment group
  • Get a single appointment group
  • Update an appointment group
  • Delete an appointment group
  • List user participants
  • List student group participants
  • Get next appointment

Was this helpful?

  1. Services
  2. Canvas LMS
  3. Resources

Appointment Groups

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 object looks like:

// Date and time for an appointment
{
  // The appointment identifier.
  "id": 987,
  // Start time for the appointment
  "start_at": "2012-07-20T15:00:00-06:00",
  // End time for the appointment
  "end_at": "2012-07-20T15:00:00-06:00"
}

An AppointmentGroup 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","end_at":"2012-07-20T15:00:00-06:00"}],
  // Boolean indicating whether observer users should be able to sign-up for an
  // appointment
  "allow_observer_signup": false,
  // 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"
}

GET /api/v1/appointment_groups

Scope: url:GET|/api/v1/appointment_groups

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

Request Parameters:

Parameter
Type
Description

scope

string

Defaults to “reservable”

Allowed values: reservable, manageable

context_codes[]

string

Array of context codes used to limit returned results.

include_past_appointments

boolean

Defaults to false. If true, includes past appointment groups

include[]

string

Array of additional information to include.

  • “appointments”

    calendar event time slots for this appointment group

  • “child_events”

    reservations of those time slots

  • “participant_count”

    number of reservations

  • “reserved_times”

    the event id, start time and end time of reservations the current user has made)

  • “all_context_codes”

    all context codes associated with this appointment group

Allowed values: appointments, child_events, participant_count, reserved_times, all_context_codes

POST /api/v1/appointment_groups

Scope: url: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:

Parameter
Type
Description

appointment_group[context_codes][]

Required string

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][]

string

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]

Required string

Short title for the appointment group.

appointment_group[description]

string

Longer text description of the appointment group.

appointment_group[location_name]

string

Location name of the appointment group.

appointment_group[location_address]

string

Location address.

appointment_group[publish]

boolean

Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. Defaults to false.

appointment_group[participants_per_appointment]

integer

Maximum number of participants that may register for each time slot. Defaults to null (no limit).

appointment_group[min_appointments_per_participant]

integer

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]

integer

Maximum number of time slots a user may register for.

appointment_group[new_appointments][X][]

string

Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request.

appointment_group[participant_visibility]

string

  • “private”

    participants cannot see who has signed up for a particular time slot

  • “protected”

    participants can see who has signed up. Defaults to “private”.

Allowed values: private, protected

appointment_group[allow_observer_signup]

boolean

Whether observer users can sign-up for an appointment. Defaults to false.

Example Request:

curl 'https://<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 /api/v1/appointment_groups/:id

Scope: url:GET|/api/v1/appointment_groups/:id

Returns information for a single appointment group

Request Parameters:

Parameter
Type
Description

include[]

string

Array of additional information to include. See include[] argument of “List appointment groups” action.

  • “child_events”

    reservations of time slots time slots

  • “appointments”

    will always be returned

  • “all_context_codes”

    all context codes associated with this appointment group

Allowed values: child_events, appointments, all_context_codes

PUT /api/v1/appointment_groups/:id

Scope: url: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:

Parameter
Type
Description

appointment_group[context_codes][]

Required string

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][]

string

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]

string

Short title for the appointment group.

appointment_group[description]

string

Longer text description of the appointment group.

appointment_group[location_name]

string

Location name of the appointment group.

appointment_group[location_address]

string

Location address.

appointment_group[publish]

boolean

Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. Defaults to false.

appointment_group[participants_per_appointment]

integer

Maximum number of participants that may register for each time slot. Defaults to null (no limit).

appointment_group[min_appointments_per_participant]

integer

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]

integer

Maximum number of time slots a user may register for.

appointment_group[new_appointments][X][]

string

Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request.

appointment_group[participant_visibility]

string

  • “private”

    participants cannot see who has signed up for a particular time slot

  • “protected”

    participants can see who has signed up. Defaults to “private”.

Allowed values: private, protected

appointment_group[allow_observer_signup]

boolean

Whether observer users can sign-up for an appointment.

Example Request:

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

DELETE /api/v1/appointment_groups/:id

Scope: url:DELETE|/api/v1/appointment_groups/:id

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

Request Parameters:

Parameter
Type
Description

cancel_reason

string

Reason for deleting/canceling the appointment group.

Example Request:

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

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

Scope: url:GET|/api/v1/appointment_groups/:id/users

A paginated list of 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:

Parameter
Type
Description

registration_status

string

Limits results to the a given participation status, defaults to “all”

Allowed values: all, registered, registered

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

Scope: url:GET|/api/v1/appointment_groups/:id/groups

A paginated list of 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:

Parameter
Type
Description

registration_status

string

Limits results to the a given participation status, defaults to “all”

Allowed values: all, registered, registered

GET /api/v1/appointment_groups/next_appointment

Scope: url:GET|/api/v1/appointment_groups/next_appointment

Return the next appointment available to sign up for. The appointment is returned in a one-element array. If no future appointments are available, an empty array is returned.

Request Parameters:

Parameter
Type
Description

appointment_group_ids[]

string

List of ids of appointment groups to search.


PreviousAPI Token ScopesNextAssignment Extensions

Last updated 2 months ago

Was this helpful?

Returns a list of objects.

This documentation is generated directly from the Canvas LMS source code, available .

AppointmentGroupsController#index
AppointmentGroupsController#create
AppointmentGroupsController#show
AppointmentGroupsController#update
AppointmentGroupsController#destroy
AppointmentGroupsController#users
AppointmentGroupsController#groups
AppointmentGroupsController#next_appointment
on Github
List appointment groups
Create an appointment group
Get a single appointment group
Update an appointment group
Delete an appointment group
List user participants
List student group participants
Get next appointment
CalendarEvent