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 unique id of the user's section.
  "course_section_id": 1,
  
  //The state of the user's enrollment in the course.
  "enrollment_state": "active",
  
  //User can only access his or her own course section.
  "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": ,
  
  //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 URL to the Canvas web UI page for this course enrollment.
  "html_url": "https://...",
  
  //The URL to the Canvas web UI page the grades associated with this enrollment.
  "grades": "",
  
  //A description of the user.
  "user": ""
}

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:

  • 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, "active"|"invited"|"creation_pending"|"deleted"|"rejected"|"completed"|"inactive"

    Filter by enrollment state. If omitted, 'active' and 'invited' enrollments are returned.

Returns a list of Enrollments

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:

  • enrollment[user_id]
    String

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

  • enrollment[type]
    String, "StudentEnrollment"|"TeacherEnrollment"|"TaEnrollment"|"ObserverEnrollment"|"DesignerEnrollment"

    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.

  • enrollment[role]
    Optional, String

    Assigns a custom course-level role to the user.

  • enrollment[enrollment_state]
    Optional, String, "active"|"invited"

    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.'

  • enrollment[course_section_id]
    Optional, 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]
    Optional, Boolean

    If a teacher or TA enrollment, teacher/TA will be restricted to the section given by course_section_id.

  • enrollment[notify]
    Optional, Boolean

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

  • enrollment[self_enrollment_code]
    Optional, 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.

Example Request:

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

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

Conclude an enrollment EnrollmentsApiController#destroy

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

Delete or conclude an enrollment.

Request Parameters:

  • task
    String, "conclude"|"delete"

    The action to take on the enrollment.

Example Request:

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