Enrollments API

API for creating and viewing course enrollments

A Grade object looks like:

{
  // The URL to the Canvas web UI page for the user's grades, if this is a student
  // enrollment.
  "html_url": "",
  // The user's current grade in the class. Only included if user has permissions to
  // view this grade.
  "current_grade": "",
  // The user's final grade for the class. Only included if user has permissions to
  // view this grade.
  "final_grade": "",
  // The user's current score in the class. Only included if user has permissions to
  // view this score.
  "current_score": "",
  // The user's final score for the class. Only included if user has permissions to
  // view this score.
  "final_score": ""
}

An Enrollment object looks like:

{
  // The ID of the enrollment.
  "id": 1,
  // The unique id of the course.
  "course_id": 1,
  // The SIS Course ID in which the enrollment is associated. Only displayed if
  // present. This field is only included if the user has permission to view SIS
  // information.
  "sis_course_id": "SHEL93921",
  // The Course Integration ID in which the enrollment is associated. This field is
  // only included if the user has permission to view SIS information.
  "course_integration_id": "SHEL93921",
  // The unique id of the user's section.
  "course_section_id": 1,
  // The Section Integration ID in which the enrollment is associated. This field is
  // only included if the user has permission to view SIS information.
  "section_integration_id": "SHEL93921",
  // The SIS Section ID in which the enrollment is associated. Only displayed if
  // present. This field is only included if the user has permission to view SIS
  // information.
  "sis_section_id": "SHEL93921",
  // The state of the user's enrollment in the course.
  "enrollment_state": "active",
  // User can only access his or her own course section. Applies to Teacher and TA
  // enrollments.
  "limit_privileges_to_course_section": true,
  // The unique identifier for the SIS import. This field is only included if the
  // user has permission to manage SIS information.
  "sis_import_id": 83,
  // The unique id of the user's account.
  "root_account_id": 1,
  // The enrollment type. One of 'StudentEnrollment', 'TeacherEnrollment',
  // 'TaEnrollment', 'DesignerEnrollment', 'ObserverEnrollment'.
  "type": "StudentEnrollment",
  // The unique id of the user.
  "user_id": 1,
  // The unique id of the associated user. Will be null unless type is
  // ObserverEnrollment.
  "associated_user_id": null,
  // The enrollment role, for course-level permissions. This field will match `type`
  // if the enrollment role has not been customized.
  "role": "StudentEnrollment",
  // The updated time of the enrollment, in ISO8601 format.
  "updated_at": "2012-04-18T23:08:51Z",
  // The start time of the enrollment, in ISO8601 format.
  "start_at": "2012-04-18T23:08:51Z",
  // The end time of the enrollment, in ISO8601 format.
  "end_at": "2012-04-18T23:08:51Z",
  // The last activity time of the user for the enrollment, in ISO8601 format.
  "last_activity_at": "2012-04-18T23:08:51Z",
  // The total activity time of the user for the enrollment, in seconds.
  "total_activity_time": 260,
  // The URL to the Canvas web UI page for this course enrollment.
  "html_url": "https://...",
  // The URL to the Canvas web UI page containing the grades associated with this
  // enrollment.
  "grades": null,
  // optional: The student's score in the course, ignoring ungraded assignments.
  // (applies only to student enrollments, and only available in course endpoints)
  "computed_current_score": 90.25,
  // optional: The student's score in the course including ungraded assignments with
  // a score of 0. (applies only to student enrollments, and only available in course
  // endpoints)
  "computed_final_score": 80.67,
  // optional: The letter grade equivalent of computed_current_score, if available.
  // (applies only to student enrollments, and only available in course endpoints)
  "computed_current_grade": "A-",
  // optional: The letter grade equivalent of computed_final_score, if available.
  // (applies only to student enrollments, and only available in course endpoints)
  "computed_final_grade": "B-",
  // optional: Indicates whether the course the enrollment belongs to has the
  // Multiple Grading Periods feature enabled. (applies only to student enrollments,
  // and only available in course endpoints)
  "multiple_grading_periods_enabled": true,
  // optional: Indicates whether the course the enrollment belongs to has the Display
  // Totals for 'All Grading Periods' feature enabled. (applies only to student
  // enrollments, and only available in course endpoints)
  "totals_for_all_grading_periods_option": true,
  // optional: The name of the currently active grading period, if one exists. If the
  // course the enrollment belongs to does not have Multiple Grading Periods enabled,
  // or if no currently active grading period exists, the value will be null.
  // (applies only to student enrollments, and only available in course endpoints)
  "current_grading_period_title": "Fall Grading Period",
  // optional: The id of the currently active grading period, if one exists. If the
  // course the enrollment belongs to does not have Multiple Grading Periods enabled,
  // or if no currently active grading period exists, the value will be null.
  // (applies only to student enrollments, and only available in course endpoints)
  "current_grading_period_id": 5,
  // optional: The student's score in the course for the current grading period,
  // ignoring ungraded assignments. If the course the enrollment belongs to does not
  // have Multiple Grading Periods enabled, or if no currently active grading period
  // exists, the value will be null. (applies only to student enrollments, and only
  // available in course endpoints)
  "current_period_computed_current_score": 95.8,
  // optional: The student's score in the course for the current grading period,
  // including ungraded assignments with a score of 0. If the course the enrollment
  // belongs to does not have Multiple Grading Periods enabled, or if no currently
  // active grading period exists, the value will be null. (applies only to student
  // enrollments, and only available in course endpoints)
  "current_period_computed_final_score": 85.25,
  // optional: The letter grade equivalent of current_period_computed_current_score,
  // if available. If the course the enrollment belongs to does not have Multiple
  // Grading Periods enabled, or if no currently active grading period exists, the
  // value will be null. (applies only to student enrollments, and only available in
  // course endpoints)
  "current_period_computed_current_grade": "A",
  // optional: The letter grade equivalent of current_period_computed_final_score, if
  // available. If the course the enrollment belongs to does not have Multiple
  // Grading Periods enabled, or if no currently active grading period exists, the
  // value will be null. (applies only to student enrollments, and only available in
  // course endpoints)
  "current_period_computed_final_grade": "B"
}

List enrollments EnrollmentsApiController#index

GET /api/v1/courses/:course_id/enrollments

GET /api/v1/sections/:section_id/enrollments

GET /api/v1/users/:user_id/enrollments

Depending on the URL given, return either (1) all of the enrollments in a course, (2) all of the enrollments in a section or (3) all of a user's enrollments. This includes student, teacher, TA, and observer enrollments.

If a user has multiple enrollments in a context (e.g. as a teacher and a student or in multiple course sections), each enrollment will be listed separately.

note: Currently, only an admin user can return other users' enrollments. A user can, however, return his/her own enrollments.

Request Parameters:

Parameter Type Description
type[] string

A list of enrollment types to return. Accepted values are 'StudentEnrollment', 'TeacherEnrollment', 'TaEnrollment', 'DesignerEnrollment', and 'ObserverEnrollment.' If omitted, all enrollment types are returned. This argument is ignored if `role` is given.

role[] string

A list of enrollment roles to return. Accepted values include course-level roles created by the Add Role API as well as the base enrollment types accepted by the `type` argument above.

state[] string

Filter by enrollment state. If omitted, 'active' and 'invited' enrollments are returned. When querying a user's enrollments (either via user_id argument or via user enrollments endpoint), the following additional synthetic states are supported: “current_and_invited”|“current_and_future”|“current_and_concluded”

Allowed values: active, invited, creation_pending, deleted, rejected, completed, inactive

include[] string

Array of additional information to include on the enrollment or user records. “avatar_url” and “group_ids” will be returned on the user record.

Allowed values: avatar_url, group_ids, locked, observed_users, can_be_removed

user_id string

Filter by user_id (only valid for course or section enrollment queries). If set to the current user's id, this is a way to determine if the user has any enrollments in the course or section, independent of whether the user has permission to view other people on the roster.

grading_period_id integer

Return grades for the given grading_period. If this parameter is not specified, the returned grades will be for the whole course.

Returns a list of Enrollments

Enrollment by ID EnrollmentsApiController#show

GET /api/v1/accounts/:account_id/enrollments/:id

Get an Enrollment object by Enrollment ID

Request Parameters:

Parameter Type Description
id Required integer

The ID of the enrollment object

Returns a Enrollment

Enroll a user EnrollmentsApiController#create

POST /api/v1/courses/:course_id/enrollments

POST /api/v1/sections/:section_id/enrollments

Create a new user enrollment for a course or section.

Request Parameters:

Parameter Type Description
enrollment[user_id] Required string

The ID of the user to be enrolled in the course.

enrollment[type] Required string

Enroll the user as a student, teacher, TA, observer, or designer. If no value is given, the type will be inferred by enrollment if supplied, otherwise 'StudentEnrollment' will be used.

Allowed values: StudentEnrollment, TeacherEnrollment, TaEnrollment, ObserverEnrollment, DesignerEnrollment

enrollment[role] Deprecated

Assigns a custom course-level role to the user.

enrollment[role_id] integer

Assigns a custom course-level role to the user.

enrollment[enrollment_state] string

If set to 'active,' student will be immediately enrolled in the course. Otherwise they will be required to accept a course invitation. Default is 'invited.'.

If set to 'inactive', student will be listed in the course roster for teachers, but will not be able to participate in the course until their enrollment is activated.

Allowed values: active, invited, inactive

enrollment[course_section_id] integer

The ID of the course section to enroll the student in. If the section-specific URL is used, this argument is redundant and will be ignored.

enrollment[limit_privileges_to_course_section] boolean

If set, the enrollment will only allow the user to see and interact with users enrolled in the section given by course_section_id.

  • For teachers and TAs, this includes grading privileges.

  • Section-limited students will not see any users (including teachers and TAs) not enrolled in their sections.

  • Users may have other enrollments that grant privileges to multiple sections in the same course.

enrollment[notify] boolean

If true, a notification will be sent to the enrolled user. Notifications are not sent by default.

enrollment[self_enrollment_code] string

If the current user is not allowed to manage enrollments in this course, but the course allows self-enrollment, the user can self- enroll as a student in the default section by passing in a valid code. When self-enrolling, the user_id must be 'self'. The enrollment_state will be set to 'active' and all other arguments will be ignored.

enrollment[self_enrolled] boolean

If true, marks the enrollment as a self-enrollment, which gives students the ability to drop the course if desired. Defaults to false.

enrollment[associated_user_id] integer

For an observer enrollment, the ID of a student to observe. The caller must have manage_students permission in the course. This is a one-off operation; to automatically observe all a student's enrollments (for example, as a parent), please use the User Observees API.

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments \
  -X POST \
  -F 'enrollment[user_id]=1' \
  -F 'enrollment[type]=StudentEnrollment' \
  -F 'enrollment[enrollment_state]=active' \
  -F 'enrollment[course_section_id]=1' \
  -F 'enrollment[limit_privileges_to_course_section]=true' \
  -F 'enrollment[notify]=false'

curl https://<canvas>/api/v1/courses/:course_id/enrollments \
  -X POST \
  -F 'enrollment[user_id]=2' \
  -F 'enrollment[type]=StudentEnrollment'
Returns a Enrollment

Conclude, deactivate, or delete an enrollment EnrollmentsApiController#destroy

DELETE /api/v1/courses/:course_id/enrollments/:id

Conclude, deactivate, or delete an enrollment. If the task argument isn't given, the enrollment will be concluded.

Request Parameters:

Parameter Type Description
task string

The action to take on the enrollment. When inactive, a user will still appear in the course roster to admins, but be unable to participate. (“inactivate” and “deactivate” are equivalent tasks)

Allowed values: conclude, delete, inactivate, deactivate

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id \
  -X DELETE \
  -F 'task=conclude'
Returns a Enrollment

Re-activate an enrollment EnrollmentsApiController#reactivate

PUT /api/v1/courses/:course_id/enrollments/:id/reactivate

Activates an inactive enrollment

Example Request:

curl https://<canvas>/api/v1/courses/:course_id/enrollments/:enrollment_id/reactivate \
  -X PUT
Returns a Enrollment