Users
API for accessing information on the current and other users.
Throughout this API, the :user_id
parameter can be replaced with self
as a shortcut for the id of the user accessing the API. For instance, users/:user_id/page_views
can be accessed as users/self/page_views
to access the current user's page views.
API for manipulating course nicknames
Course nicknames are alternate names for courses that are unique to each user. They are useful when the course's name is too long or less meaningful. If a user defines a nickname for a course, that name will be returned by the API in place of the course's actual name.
An UserDisplay object looks like:
An AnonymousUserDisplay object looks like:
An User object looks like:
A Profile object looks like:
An Avatar object looks like:
A PageView object looks like:
A PageViewLinks object looks like:
A CourseNickname object looks like:
GET /api/v1/accounts/:account_id/users
GET /api/v1/accounts/:account_id/users
Scope: url:GET|/api/v1/accounts/:account_id/users
A paginated list of users associated with this account.
Request Parameters:
search_term
string
The partial name or full ID of the users to match and return in the results list. Must be at least 3 characters.
Note that the API will prefer matching on canonical user ID if the ID has a numeric form. It will only search against other fields if non-numeric in form, or if the numeric value doesn’t yield any matches. Queries by administrative users will search on SIS ID, Integration ID, login ID, name, or email address
enrollment_type
string
When set, only return users enrolled with the specified course-level base role. This can be a base role type of ‘student’, ‘teacher’, ‘ta’, ‘observer’, or ‘designer’.
sort
string
The column to sort results by.
Allowed values: username
, email
, sis_id
, integration_id
, last_login
order
string
The order to sort the given column by.
Allowed values: asc
, desc
include_deleted_users
boolean
When set to true and used with an account context, returns users who have deleted pseudonyms for the context
Returns a list of User objects.
UsersController#activity_stream
GET /api/v1/users/self/activity_stream
GET /api/v1/users/self/activity_stream
Scope: url:GET|/api/v1/users/self/activity_stream
GET /api/v1/users/activity_stream
GET /api/v1/users/activity_stream
Scope: url:GET|/api/v1/users/activity_stream
Returns the current user’s global activity stream, paginated.
There are many types of objects that can be returned in the activity stream. All object types have the same basic set of shared attributes:
In addition, each item type has its own set of attributes available.
DiscussionTopic:
For DiscussionTopic, the message is truncated at 4kb.
Announcement:
For Announcement, the message is truncated at 4kb.
Conversation:
Message:
Submission:
Returns an Submission with its Course and Assignment data.
Conference:
Collaboration:
AssessmentRequest:
Request Parameters:
only_active_courses
boolean
If true, will only return objects for courses the user is actively participating in
UsersController#activity_stream_summary
GET /api/v1/users/self/activity_stream/summary
GET /api/v1/users/self/activity_stream/summary
Scope: url:GET|/api/v1/users/self/activity_stream/summary
Returns a summary of the current user’s global activity stream.
Request Parameters:
only_active_courses
boolean
If true, will only return objects for courses the user is actively participating in
Example Response:
GET /api/v1/users/self/todo
GET /api/v1/users/self/todo
Scope: url:GET|/api/v1/users/self/todo
A paginated list of the current user’s list of todo items.
There is a limit to the number of items returned.
The ‘ignore` and `ignore_permanently` URLs can be used to update the user’s preferences on what items will be displayed. Performing a DELETE request against the ‘ignore` URL will hide that item from future todo item requests, until the item changes. Performing a DELETE request against the `ignore_permanently` URL will hide that item forever.
Request Parameters:
include[]
string
“ungraded_quizzes”
Optionally include ungraded quizzes (such as practice quizzes and surveys) in the list. These will be returned under a quiz key instead of an assignment key in response elements.
Allowed values: ungraded_quizzes
Example Response:
UsersController#todo_item_count
GET /api/v1/users/self/todo_item_count
GET /api/v1/users/self/todo_item_count
Scope: url:GET|/api/v1/users/self/todo_item_count
Counts of different todo items such as the number of assignments needing grading as well as the number of assignments needing submitting.
There is a limit to the number of todo items this endpoint will count. It will only look at the first 100 todo items for the user. If the user has more than 100 todo items this count may not be reliable. The largest reliable number for both counts is 100.
Request Parameters:
include[]
string
“ungraded_quizzes”
Optionally include ungraded quizzes (such as practice quizzes and surveys) in the list. These will be returned under a quiz key instead of an assignment key in response elements.
Allowed values: ungraded_quizzes
Example Response:
UsersController#upcoming_events
GET /api/v1/users/self/upcoming_events
GET /api/v1/users/self/upcoming_events
Scope: url:GET|/api/v1/users/self/upcoming_events
A paginated list of the current user’s upcoming events.
Example Response:
UsersController#missing_submissions
GET /api/v1/users/:user_id/missing_submissions
GET /api/v1/users/:user_id/missing_submissions
Scope: url:GET|/api/v1/users/:user_id/missing_submissions
A paginated list of past-due assignments for which the student does not have a submission. The user sending the request must either be the student, an admin or a parent observer using the parent app
Request Parameters:
user_id
string
the student’s ID
observed_user_id
string
Return missing submissions for the given observed user. Must be accompanied by course_ids[]. The user making the request must be observing the observed user in all the courses specified by course_ids[].
include[]
string
“planner_overrides”
Optionally include the assignment’s associated planner override, if it exists, for the current user. These will be returned under a planner_override key
“course”
Optionally include the assignments’ courses
Allowed values: planner_overrides
, course
filter[]
string
“submittable”
Only return assignments that the current user can submit (i.e. filter out locked assignments)
“current_grading_period”
Only return missing assignments that are in the current grading period
Allowed values: submittable
, current_grading_period
course_ids[]
string
Optionally restricts the list of past-due assignments to only those associated with the specified course IDs. Required if observed_user_id is passed.
Returns a list of Assignment objects.
UsersController#ignore_stream_item
DELETE /api/v1/users/self/activity_stream/:id
DELETE /api/v1/users/self/activity_stream/:id
Scope: url:DELETE|/api/v1/users/self/activity_stream/:id
Hide the given stream item.
Example Request:
Example Response:
UsersController#ignore_all_stream_items
DELETE /api/v1/users/self/activity_stream
DELETE /api/v1/users/self/activity_stream
Scope: url:DELETE|/api/v1/users/self/activity_stream
Hide all stream items for the user
Example Request:
Example Response:
POST /api/v1/users/:user_id/files
POST /api/v1/users/:user_id/files
Scope: url:POST|/api/v1/users/:user_id/files
Upload a file to the user’s personal files section.
This API endpoint is the first step in uploading a file to a user’s files. See the File Upload Documentation for details on the file upload workflow.
Note that typically users will only be able to upload files to their own files section. Passing a user_id of self
is an easy shortcut to specify the current user.
GET /api/v1/users/:id
GET /api/v1/users/:id
Scope: url:GET|/api/v1/users/:id
Shows details for user.
Also includes an attribute “permissions”, a non-comprehensive list of permissions for the user. Example:
Request Parameters:
include[]
string
Array of additional information to include on the user record. “locale”, “avatar_url”, “permissions”, “email”, and “effective_locale” will always be returned
Allowed values: uuid
, last_login
Example Request:
Returns an User object.
POST /api/v1/accounts/:account_id/users
POST /api/v1/accounts/:account_id/users
Scope: url:POST|/api/v1/accounts/:account_id/users
Create and return a new user and pseudonym for an account.
DEPRECATED (for self-registration only)
If you don’t have the “Modify
login details for users“ permission, but self-registration is enabled on the account, you can still use this endpoint to register new users. Certain fields will be required, and others will be ignored (see below).
Request Parameters:
user[name]
string
The full name of the user. This name will be used by teacher for grading. Required if this is a self-registration.
user[short_name]
string
User’s name as it will be displayed in discussions, messages, and comments.
user[sortable_name]
string
User’s name as used to sort alphabetically in lists.
user[time_zone]
string
The time zone for the user. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.
user[locale]
string
The user’s preferred language, from the list of languages Canvas supports. This is in RFC-5646 format.
user[terms_of_use]
boolean
Whether the user accepts the terms of use. Required if this is a self-registration and this canvas instance requires users to accept the terms (on by default).
If this is true, it will mark the user as having accepted the terms of use.
user[skip_registration]
boolean
Automatically mark the user as registered.
If this is true, it is recommended to set "pseudonym[send_confirmation]"
to true as well. Otherwise, the user will not receive any messages about their account creation.
The users communication channel confirmation can be skipped by setting "communication_channel[skip_confirmation]"
to true as well.
pseudonym[unique_id]
Required string
User’s login ID. If this is a self-registration, it must be a valid email address.
pseudonym[password]
string
User’s password. Cannot be set during self-registration.
pseudonym[sis_user_id]
string
SIS ID for the user’s account. To set this parameter, the caller must be able to manage SIS permissions.
pseudonym[integration_id]
string
Integration ID for the login. To set this parameter, the caller must be able to manage SIS permissions. The Integration ID is a secondary identifier useful for more complex SIS integrations.
pseudonym[send_confirmation]
boolean
Send user notification of account creation if true. Automatically set to true during self-registration.
pseudonym[force_self_registration]
boolean
Send user a self-registration style email if true. Setting it means the users will get a notification asking them to “complete the registration process” by clicking it, setting a password, and letting them in. Will only be executed on if the user does not need admin approval. Defaults to false unless explicitly provided.
pseudonym[authentication_provider_id]
string
The authentication provider this login is associated with. Logins associated with a specific provider can only be used with that provider. Legacy providers (LDAP, CAS, SAML) will search for logins associated with them, or unassociated logins. New providers will only search for logins explicitly associated with them. This can be the integer ID of the provider, or the type of the provider (in which case, it will find the first matching provider).
communication_channel[type]
string
The communication channel type, e.g. ‘email’ or ‘sms’.
communication_channel[address]
string
The communication channel address, e.g. the user’s email address.
communication_channel[confirmation_url]
boolean
Only valid for account admins. If true, returns the new user account confirmation URL in the response.
communication_channel[skip_confirmation]
boolean
Only valid for site admins and account admins making requests; If true, the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.
If this is true, it is recommended to set "pseudonym[send_confirmation]"
to true as well. Otherwise, the user will not receive any messages about their account creation.
force_validations
boolean
If true, validations are performed on the newly created user (and their associated pseudonym) even if the request is made by a privileged user like an admin. When set to false, or not included in the request parameters, any newly created users are subject to validations unless the request is made by a user with a ‘manage_user_logins’ right. In which case, certain validations such as ‘require_acceptance_of_terms’ and ‘require_presence_of_name’ are not enforced. Use this parameter to return helpful json errors while building users with an admin request.
enable_sis_reactivation
boolean
When true, will first try to re-activate a deleted user with matching sis_user_id if possible. This is commonly done with user and communication_channel so that the default communication_channel is also restored.
destination
URL
If you’re setting the password for the newly created user, you can provide this param with a valid URL pointing into this Canvas installation, and the response will include a destination field that’s a URL that you can redirect a browser to and have the newly created user automatically logged in. The URL is only valid for a short time, and must match the domain this request is directed to, and be for a well-formed path that Canvas can recognize.
initial_enrollment_type
string
‘observer` if doing a self-registration with a pairing code. This allows setting the password during user creation.
pairing_code[code]
string
If provided and valid, will link the new user as an observer to the student’s whose pairing code is given.
Returns an User object.
UsersController#create_self_registered_user
POST /api/v1/accounts/:account_id/self_registration
POST /api/v1/accounts/:account_id/self_registration
Scope: url:POST|/api/v1/accounts/:account_id/self_registration
Self register and return a new user and pseudonym for an account.
If self-registration is enabled on the account, you can use this endpoint to self register new users.
Request Parameters:
user[name]
Required string
The full name of the user. This name will be used by teacher for grading.
user[short_name]
string
User’s name as it will be displayed in discussions, messages, and comments.
user[sortable_name]
string
User’s name as used to sort alphabetically in lists.
user[time_zone]
string
The time zone for the user. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.
user[locale]
string
The user’s preferred language, from the list of languages Canvas supports. This is in RFC-5646 format.
user[terms_of_use]
Required boolean
Whether the user accepts the terms of use.
pseudonym[unique_id]
Required string
User’s login ID. Must be a valid email address.
communication_channel[type]
string
The communication channel type, e.g. ‘email’ or ‘sms’.
communication_channel[address]
string
The communication channel address, e.g. the user’s email address.
Returns an User object.
GET /api/v1/users/:id/settings
GET /api/v1/users/:id/settings
Scope: url:GET|/api/v1/users/:id/settings
PUT /api/v1/users/:id/settings
PUT /api/v1/users/:id/settings
Scope: url:PUT|/api/v1/users/:id/settings
Update an existing user’s settings.
Request Parameters:
manual_mark_as_read
boolean
If true, require user to manually mark discussion posts as read (don’t auto-mark as read).
release_notes_badge_disabled
boolean
If true, hide the badge for new release notes.
collapse_global_nav
boolean
If true, the user’s page loads with the global navigation collapsed
collapse_course_nav
boolean
If true, the user’s course pages will load with the course navigation collapsed.
hide_dashcard_color_overlays
boolean
If true, images on course cards will be presented without being tinted to match the course color.
comment_library_suggestions_enabled
boolean
If true, suggestions within the comment library will be shown.
elementary_dashboard_disabled
boolean
If true, will display the user’s preferred class Canvas dashboard view instead of the canvas for elementary view.
Example Request:
UsersController#get_custom_colors
GET /api/v1/users/:id/colors
GET /api/v1/users/:id/colors
Scope: url:GET|/api/v1/users/:id/colors
Returns all custom colors that have been saved for a user.
Example Request:
Example Response:
UsersController#get_custom_color
GET /api/v1/users/:id/colors/:asset_string
GET /api/v1/users/:id/colors/:asset_string
Scope: url:GET|/api/v1/users/:id/colors/:asset_string
Returns the custom colors that have been saved for a user for a given context.
The asset_string parameter should be in the format ‘context_id’, for example ‘course_42’.
Example Request:
Example Response:
UsersController#set_custom_color
PUT /api/v1/users/:id/colors/:asset_string
PUT /api/v1/users/:id/colors/:asset_string
Scope: url:PUT|/api/v1/users/:id/colors/:asset_string
Updates a custom color for a user for a given context. This allows colors for the calendar and elsewhere to be customized on a user basis.
The asset string parameter should be in the format ‘context_id’, for example ‘course_42’
Request Parameters:
hexcode
string
The hexcode of the color to set for the context, if you choose to pass the hexcode as a query parameter rather than in the request body you should NOT include the ‘#’ unless you escape it first.
Example Request:
Example Response:
UsersController#set_text_editor_preference
PUT /api/v1/users/:id/text_editor_preference
PUT /api/v1/users/:id/text_editor_preference
Scope: url:PUT|/api/v1/users/:id/text_editor_preference
Updates a user’s default choice for text editor. This allows the Choose an Editor propmts to preload the user’s preference.
Request Parameters:
text_editor_preference
string
The identifier for the editor.
Allowed values: block_editor
, rce
, ``
Example Request:
Example Response:
UsersController#get_dashboard_positions
GET /api/v1/users/:id/dashboard_positions
GET /api/v1/users/:id/dashboard_positions
Scope: url:GET|/api/v1/users/:id/dashboard_positions
Returns all dashboard positions that have been saved for a user.
Example Request:
Example Response:
UsersController#set_dashboard_positions
PUT /api/v1/users/:id/dashboard_positions
PUT /api/v1/users/:id/dashboard_positions
Scope: url:PUT|/api/v1/users/:id/dashboard_positions
Updates the dashboard positions for a user for a given context. This allows positions for the dashboard cards and elsewhere to be customized on a per user basis.
The asset string parameter should be in the format ‘context_id’, for example ‘course_42’
Example Request:
Example Response:
PUT /api/v1/users/:id
PUT /api/v1/users/:id
Scope: url:PUT|/api/v1/users/:id
Modify an existing user. To modify a user’s login, see the documentation for logins.
Request Parameters:
user[name]
string
The full name of the user. This name will be used by teacher for grading.
user[short_name]
string
User’s name as it will be displayed in discussions, messages, and comments.
user[sortable_name]
string
User’s name as used to sort alphabetically in lists.
user[time_zone]
string
The time zone for the user. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.
user[email]
string
The default email address of the user.
user[locale]
string
The user’s preferred language, from the list of languages Canvas supports. This is in RFC-5646 format.
user[avatar][token]
string
A unique representation of the avatar record to assign as the user’s current avatar. This token can be obtained from the user avatars endpoint. This supersedes the user [avatar] [url] argument, and if both are included the url will be ignored. Note: this is an internal representation and is subject to change without notice. It should be consumed with this api endpoint and used in the user update endpoint, and should not be constructed by the client.
user[avatar][url]
string
To set the user’s avatar to point to an external url, do not include a token and instead pass the url here. Warning: For maximum compatibility, please use 128 px square images.
user[avatar][state]
string
To set the state of user’s avatar. Only valid for account administrator.
Allowed values: none
, submitted
, approved
, locked
, reported
, re_reported
user[title]
string
Sets a title on the user profile. (See Get user profile.) Profiles must be enabled on the root account.
user[bio]
string
Sets a bio on the user profile. (See Get user profile.) Profiles must be enabled on the root account.
user[pronunciation]
string
Sets name pronunciation on the user profile. (See Get user profile.) Profiles and name pronunciation must be enabled on the root account.
user[pronouns]
string
Sets pronouns on the user profile. Passing an empty string will empty the user’s pronouns Only Available Pronouns set on the root account are allowed Adding and changing pronouns must be enabled on the root account.
user[event]
string
Suspends or unsuspends all logins for this user that the calling user has permission to
Allowed values: suspend
, unsuspend
override_sis_stickiness
boolean
Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness