Enrollments API
API for creating and viewing course enrollments
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[]
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[]
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[]
Filter by enrollment state. Accepted values are 'active', 'invited', and 'creation_pending', 'deleted', 'rejected', 'completed', and 'inactive'. If omitted, 'active' and 'invited' enrollments are returned.
API response field:
-
id
The unique id of the enrollment.
-
course_id
The unique id of the course.
-
course_section_id
The unique id of the user's section.
-
enrollment_state
The state of the user's enrollment in the course.
-
limit_privileges_to_course_section
User can only access his or her own course section.
-
root_account_id
The unique id of the user's account.
-
type
The type of the enrollment.
-
role
The enrollment role, for course-level permissions.
-
user_id
The unique id of the user.
-
html_url
The URL to the Canvas web UI page for this course enrollment.
-
grades[html_url]
The URL to the Canvas web UI page for the user's grades, if this is a student enrollment.
-
grades[current_grade]
The user's current grade in the class. Only included if user has permissions to view this grade.
-
grades[final_grade]
The user's final grade for the class. Only included if user has permissions to view this grade.
-
user[id]
The unique id of the user.
-
user[login_id]
The unique login of the user.
-
user[name]
The name of the user.
-
user[short_name]
The short name of the user.
-
user[sortable_name]
The sortable name of the user.
Example Response:
[
{
"id": 1,
"course_id": 1,
"course_section_id": 1,
"enrollment_state": "active",
"limit_privileges_to_course_section": true,
"root_account_id": 1,
"type": "StudentEnrollment",
"user_id": 1,
"html_url": "https://...",
"grades": {
"html_url": "https://...",
},
"user": {
"id": 1,
"login_id": "bieberfever@example.com",
"name": "Justin Bieber",
"short_name": "Justin B.",
"sortable_name": "Bieber, Justin"
}
},
{
"id": 2,
"course_id": 1,
"course_section_id": 2,
"enrollment_state": "active",
"limit_privileges_to_course_section": false,
"root_account_id": 1,
"type": "TeacherEnrollment",
"user_id": 2,
"html_url": "https://...",
"grades": {
"html_url": "https://...",
},
"user": {
"id": 2,
"login_id": "changyourmind@example.com",
"name": "Señor Chang",
"short_name": "S. Chang",
"sortable_name": "Chang, Señor"
}
},
{
"id": 3,
"course_id": 1,
"course_section_id": 2,
"enrollment_state": "active",
"limit_privileges_to_course_section": false,
"root_account_id": 1,
"type": "StudentEnrollment",
"user_id": 2,
"html_url": "https://...",
"grades": {
"html_url": "https://...",
},
"user": {
"id": 2,
"login_id": "changyourmind@example.com",
"name": "Señor Chang",
"short_name": "S. Chang",
"sortable_name": "Chang, Señor"
}
}
]
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]
- String
- Optional
-
Assigns a custom course-level role to the user.
-
enrollment[enrollment_state]
- String
- Optional, active|invited
- 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.'
-
enrollment[course_section_id]
- Integer
- Optional
-
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
- Optional
-
If a teacher or TA enrollment, teacher/TA will be restricted to the section given by course_section_id.
-
enrollment[notify]
- Boolean
- Optional
-
If false (0 or "false"), a notification will not be sent to the enrolled user. Notifications are sent by default.
Conclude an enrollment EnrollmentsApiController#destroy
DELETE /api/v1/courses/:course_id/enrollments/:id
Delete or conclude an enrollment.
Request Parameters:
-
task
- conclude|delete
- String
-
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'
Example Response:
{
"root_account_id": 15,
"id": 75,
"user_id": 4,
"course_section_id": 12,
"limit_privileges_to_course_section": false,
"enrollment_state": "completed",
"course_id": 12,
"type": "StudentEnrollment",
"html_url": "http://www.example.com/courses/12/users/4",
"grades": { "html_url": "http://www.example.com/courses/12/grades/4" },
"associated_user_id": null,
"updated_at": "2012-04-18T23:08:51Z"
}