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:

// This mini-object is used for secondary user responses, when we just want to
// provide enough information to display a user.
{
  // The ID of the user.
  "id": 2,
  // A short name the user has selected, for use in conversations or other less
  // formal places through the site.
  "short_name": "Shelly",
  // If avatars are enabled, this field will be included and contain a url to
  // retrieve the user's avatar.
  "avatar_image_url": "https://en.gravatar.com/avatar/d8cb8c8cd40ddf0cd05241443a591868?s=80&r=g",
  // URL to access user, either nested to a context or directly.
  "html_url": "https://school.instructure.com/courses/:course_id/users/:user_id"
}

An AnonymousUserDisplay object looks like:

// This mini-object is returned in place of UserDisplay when returning student
// data for anonymous assignments, and includes an anonymous ID to identify a
// user within the scope of a single assignment.
{
  // A unique short ID identifying this user within the scope of a particular
  // assignment.
  "anonymous_id": "xn29Q",
  // A URL to retrieve a generic avatar.
  "avatar_image_url": "https://en.gravatar.com/avatar/d8cb8c8cd40ddf0cd05241443a591868?s=80&r=g",
  // The anonymized display name for the student.
  "display_name": "Student 2"
}

An User object looks like:

// A Canvas user, e.g. a student, teacher, administrator, observer, etc.
{
  // The ID of the user.
  "id": 2,
  // The name of the user.
  "name": "Sheldon Cooper",
  // The name of the user that is should be used for sorting groups of users, such
  // as in the gradebook.
  "sortable_name": "Cooper, Sheldon",
  // The last name of the user.
  "last_name": "Cooper",
  // The first name of the user.
  "first_name": "Sheldon",
  // A short name the user has selected, for use in conversations or other less
  // formal places through the site.
  "short_name": "Shelly",
  // The SIS ID associated with the user.  This field is only included if the user
  // came from a SIS import and has permissions to view SIS information.
  "sis_user_id": "SHEL93921",
  // The id of the SIS import.  This field is only included if the user came from
  // a SIS import and has permissions to manage SIS information.
  "sis_import_id": 18,
  // The integration_id associated with the user.  This field is only included if
  // the user came from a SIS import and has permissions to view SIS information.
  "integration_id": "ABC59802",
  // The unique login id for the user.  This is what the user uses to log in to
  // Canvas.
  "login_id": "[e-mail]",
  // If avatars are enabled, this field will be included and contain a url to
  // retrieve the user's avatar.
  "avatar_url": "https://en.gravatar.com/avatar/d8cb8c8cd40ddf0cd05241443a591868?s=80&r=g",
  // Optional: If avatars are enabled and caller is admin, this field can be
  // requested and will contain the current state of the user's avatar.
  "avatar_state": "approved",
  // Optional: This field can be requested with certain API calls, and will return
  // a list of the users active enrollments. See the List enrollments API for more
  // details about the format of these records.
  "enrollments": null,
  // Optional: This field can be requested with certain API calls, and will return
  // the users primary email address.
  "email": "[e-mail]",
  // Optional: This field can be requested with certain API calls, and will return
  // the users locale in RFC 5646 format.
  "locale": "tlh",
  // Optional: This field is only returned in certain API calls, and will return a
  // timestamp representing the last time the user logged in to canvas.
  "last_login": "2012-05-30T17:45:25Z",
  // Optional: This field is only returned in certain API calls, and will return
  // the IANA time zone name of the user's preferred timezone.
  "time_zone": "America/Denver",
  // Optional: The user's bio.
  "bio": "I like the Muppets.",
  // Optional: This field is only returned if pronouns are enabled, and will
  // return the pronouns of the user.
  "pronouns": "he/him"
}

A Profile object looks like:

// Profile details for a Canvas user.
{
  // The ID of the user.
  "id": 1234,
  // Sample User
  "name": "Sample User",
  // Sample User
  "short_name": "Sample User",
  // user, sample
  "sortable_name": "user, sample",
  "title": null,
  "bio": null,
  // Name pronunciation
  "pronunciation": "Sample name pronunciation",
  // [e-mail]
  "primary_email": "[e-mail]",
  // [e-mail]
  "login_id": "[e-mail]",
  // sis1
  "sis_user_id": "sis1",
  "lti_user_id": null,
  // The avatar_url can change over time, so we recommend not caching it for more
  // than a few hours
  "avatar_url": "..url..",
  "calendar": null,
  // Optional: This field is only returned in certain API calls, and will return
  // the IANA time zone name of the user's preferred timezone.
  "time_zone": "America/Denver",
  // The users locale.
  "locale": null,
  // Optional: Whether or not the user is a K5 user. This field is nil if the user
  // settings are not for the user making the request.
  "k5_user": true,
  // Optional: Whether or not the user should see the classic font on the
  // dashboard. Only applies if k5_user is true. This field is nil if the user
  // settings are not for the user making the request.
  "use_classic_font_in_k5": false
}

An Avatar object looks like:

// Possible avatar for a user.
{
  // ['gravatar'|'attachment'|'no_pic'] The type of avatar record, for
  // categorization purposes.
  "type": "gravatar",
  // The url of the avatar
  "url": "https://secure.gravatar.com/avatar/2284...",
  // A unique representation of the avatar record which can be used to set the
  // avatar with the user update endpoint. 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.
  "token": "<opaque_token>",
  // A textual description of the avatar record.
  "display_name": "user, sample",
  // ['attachment' type only] the internal id of the attachment
  "id": 12,
  // ['attachment' type only] the content-type of the attachment.
  "content-type": "image/jpeg",
  // ['attachment' type only] the filename of the attachment
  "filename": "profile.jpg",
  // ['attachment' type only] the size of the attachment
  "size": 32649
}

A PageView object looks like:

// The record of a user page view access in Canvas
{
  // A UUID representing the page view.  This is also the unique request id
  "id": "3e246700-e305-0130-51de-02e33aa501ef",
  // If the request is from an API request, the app that generated the access
  // token
  "app_name": "Canvas for iOS",
  // The URL requested
  "url": "https://canvas.instructure.com/conversations",
  // The type of context for the request
  "context_type": "Course",
  // The type of asset in the context for the request, if any
  "asset_type": "Discussion",
  // The rails controller that handled the request
  "controller": "discussions",
  // The rails action that handled the request
  "action": "index",
  // This field is deprecated, and will always be false
  "contributed": false,
  // An approximation of how long the user spent on the page, in seconds
  "interaction_seconds": 7.21,
  // When the request was made
  "created_at": "2013-10-01T19:49:47Z",
  // A flag indicating whether the request was user-initiated, or automatic (such
  // as an AJAX call)
  "user_request": true,
  // How long the response took to render, in seconds
  "render_time": 0.369,
  // The user-agent of the browser or program that made the request
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_5) AppleWebKit/536.30.1 (KHTML, like Gecko) Version/6.0.5 Safari/536.30.1",
  // True if the request counted as participating, such as submitting homework
  "participated": false,
  // The HTTP method such as GET or POST
  "http_method": "GET",
  // The origin IP address of the request
  "remote_ip": "173.194.46.71",
  // The page view links to define the relationships
  "links": {"user":1234,"account":1234}
}

A PageViewLinks object looks like:

// The links of a page view access in Canvas
{
  // The ID of the user for this page view
  "user": 1234,
  // The ID of the context for the request (course id if context_type is Course,
  // etc)
  "context": 1234,
  // The ID of the asset for the request, if any
  "asset": 1234,
  // The ID of the actual user who made this request, if the request was made by a
  // user who was masquerading
  "real_user": 1234,
  // The ID of the account context for this page view
  "account": 1234
}

A CourseNickname object looks like:

{
  // the ID of the course
  "course_id": 88,
  // the actual name of the course
  "name": "S1048576 DPMS1200 Intro to Newtonian Mechanics",
  // the calling user's nickname for the course
  "nickname": "Physics"
}

List users in account

UsersController#api_index

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.

@example_request
  curl https://<canvas>/api/v1/accounts/self/users?search_term=<search value> \
     -X GET \
     -H 'Authorization: Bearer <token>'

Request Parameters:

Parameter	Type	Description
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.

List the activity stream

UsersController#activity_stream

GET /api/v1/users/self/activity_stream

Scope: url:GET|/api/v1/users/self/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:

{
  'created_at': '2011-07-13T09:12:00Z',
  'updated_at': '2011-07-25T08:52:41Z',
  'id': 1234,
  'title': 'Stream Item Subject',
  'message': 'This is the body text of the activity stream item. It is plain-text, and can be multiple paragraphs.',
  'type': 'DiscussionTopic|Conversation|Message|Submission|Conference|Collaboration|AssessmentRequest...',
  'read_state': false,
  'context_type': 'course', // course|group
  'course_id': 1,
  'group_id': null,
  'html_url': "http://..." // URL to the Canvas web UI for this stream item
}

In addition, each item type has its own set of attributes available.

DiscussionTopic:

{
  'type': 'DiscussionTopic',
  'discussion_topic_id': 1234,
  'total_root_discussion_entries': 5,
  'require_initial_post': true,
  'user_has_posted': true,
  'root_discussion_entries': {
    ...
  }
}

For DiscussionTopic, the message is truncated at 4kb.

Announcement:

{
  'type': 'Announcement',
  'announcement_id': 1234,
  'total_root_discussion_entries': 5,
  'require_initial_post': true,
  'user_has_posted': null,
  'root_discussion_entries': {
    ...
  }
}

For Announcement, the message is truncated at 4kb.

Conversation:

{
  'type': 'Conversation',
  'conversation_id': 1234,
  'private': false,
  'participant_count': 3,
}

Message:

{
  'type': 'Message',
  'message_id': 1234,
  'notification_category': 'Assignment Graded'
}

Submission:

Returns an Submission with its Course and Assignment data.

Conference:

{
  'type': 'Conference',
  'web_conference_id': 1234
}

Collaboration:

{
  'type': 'Collaboration',
  'collaboration_id': 1234
}

AssessmentRequest:

{
  'type': 'AssessmentRequest',
  'assessment_request_id': 1234
}

Request Parameters:

Parameter	Type	Description
only_active_courses	boolean	If true, will only return objects for courses the user is actively participating in

Activity stream summary

UsersController#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:

Parameter	Type	Description
only_active_courses	boolean	If true, will only return objects for courses the user is actively participating in

Example Response:

[
  {
    "type": "DiscussionTopic",
    "unread_count": 2,
    "count": 7
  },
  {
    "type": "Conversation",
    "unread_count": 0,
    "count": 3
  }
]

List the TODO items

UsersController#todo_items

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:

Parameter	Type	Description
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:

[
  {
    'type': 'grading',        // an assignment that needs grading
    'assignment': { .. assignment object .. },
    'ignore': '.. url ..',
    'ignore_permanently': '.. url ..',
    'html_url': '.. url ..',
    'needs_grading_count': 3, // number of submissions that need grading
    'context_type': 'course', // course|group
    'course_id': 1,
    'group_id': null,
  },
  {
    'type' => 'submitting',   // an assignment that needs submitting soon
    'assignment' => { .. assignment object .. },
    'ignore' => '.. url ..',
    'ignore_permanently' => '.. url ..',
    'html_url': '.. url ..',
    'context_type': 'course',
    'course_id': 1,
  },
  {
    'type' => 'submitting',   // a quiz that needs submitting soon
    'quiz' => { .. quiz object .. },
    'ignore' => '.. url ..',
    'ignore_permanently' => '.. url ..',
    'html_url': '.. url ..',
    'context_type': 'course',
    'course_id': 1,
  },
]

List counts for todo items

UsersController#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:

Parameter	Type	Description
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:

{
  needs_grading_count: 32,
  assignments_needing_submitting: 10
}

List upcoming assignments, calendar events

UsersController#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:

[
  {
    "id"=>597,
    "title"=>"Upcoming Course Event",
    "description"=>"Attendance is correlated with passing!",
    "start_at"=>"2013-04-27T14:33:14Z",
    "end_at"=>"2013-04-27T14:33:14Z",
    "location_name"=>"Red brick house",
    "location_address"=>"110 Top of the Hill Dr.",
    "all_day"=>false,
    "all_day_date"=>nil,
    "created_at"=>"2013-04-26T14:33:14Z",
    "updated_at"=>"2013-04-26T14:33:14Z",
    "workflow_state"=>"active",
    "context_code"=>"course_12938",
    "child_events_count"=>0,
    "child_events"=>[],
    "parent_event_id"=>nil,
    "hidden"=>false,
    "url"=>"http://www.example.com/api/v1/calendar_events/597",
    "html_url"=>"http://www.example.com/calendar?event_id=597&include_contexts=course_12938"
  },
  {
    "id"=>"assignment_9729",
    "title"=>"Upcoming Assignment",
    "description"=>nil,
    "start_at"=>"2013-04-28T14:47:32Z",
    "end_at"=>"2013-04-28T14:47:32Z",
    "all_day"=>false,
    "all_day_date"=>"2013-04-28",
    "created_at"=>"2013-04-26T14:47:32Z",
    "updated_at"=>"2013-04-26T14:47:32Z",
    "workflow_state"=>"published",
    "context_code"=>"course_12942",
    "assignment"=>{
      "id"=>9729,
      "name"=>"Upcoming Assignment",
      "description"=>nil,
      "points_possible"=>10,
      "due_at"=>"2013-04-28T14:47:32Z",
      "assignment_group_id"=>2439,
      "automatic_peer_reviews"=>false,
      "grade_group_students_individually"=>nil,
      "grading_standard_id"=>nil,
      "grading_type"=>"points",
      "group_category_id"=>nil,
      "lock_at"=>nil,
      "peer_reviews"=>false,
      "position"=>1,
      "unlock_at"=>nil,
      "course_id"=>12942,
      "submission_types"=>["none"],
      "needs_grading_count"=>0,
      "html_url"=>"http://www.example.com/courses/12942/assignments/9729"
    },
    "url"=>"http://www.example.com/api/v1/calendar_events/assignment_9729",
    "html_url"=>"http://www.example.com/courses/12942/assignments/9729"
  }
]

List Missing Submissions

UsersController#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:

Parameter	Type	Description
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.

Hide a stream item

UsersController#ignore_stream_item

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:

curl https://<canvas>/api/v1/users/self/activity_stream/<stream_item_id> \
   -X DELETE \
   -H 'Authorization: Bearer <token>'

Example Response:

{
  "hidden": true
}

Hide all stream items

UsersController#ignore_all_stream_items

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:

curl https://<canvas>/api/v1/users/self/activity_stream \
   -X DELETE \
   -H 'Authorization: Bearer <token>'

Example Response:

{
  "hidden": true
}

Upload a file

UsersController#create_file

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.

Show user details

UsersController#api_show

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:

"permissions": {
 "can_update_name": true, // Whether the user can update their name.
 "can_update_avatar": false, // Whether the user can update their avatar.
 "limit_parent_app_web_access": false // Whether the user can interact with Canvas web from the Canvas Parent app.
}

Request Parameters:

Parameter	Type	Description
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:

curl https://<canvas>/api/v1/users/self \
    -X GET \
    -H 'Authorization: Bearer <token>'

Returns an User object.

Create a user

UsersController#create

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:

Parameter	Type	Description
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.

[DEPRECATED] Self register a user

UsersController#create_self_registered_user

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:

Parameter	Type	Description
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.

Update user settings.

UsersController#settings

GET /api/v1/users/:id/settings

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

Parameter	Type	Description
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:

curl 'https://<canvas>/api/v1/users/<user_id>/settings \
  -X PUT \
  -F 'manual_mark_as_read=true'
  -H 'Authorization: Bearer <token>'

Get custom colors

UsersController#get_custom_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:

curl 'https://<canvas>/api/v1/users/<user_id>/colors/ \
  -X GET \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "custom_colors": {
    "course_42": "#abc123",
    "course_88": "#123abc"
  }
}

Get custom color

UsersController#get_custom_color

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:

curl 'https://<canvas>/api/v1/users/<user_id>/colors/<asset_string> \
  -X GET \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "hexcode": "#abc123"
}

Update custom color

UsersController#set_custom_color

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:

Parameter	Type	Description
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:

curl 'https://<canvas>/api/v1/users/<user_id>/colors/<asset_string> \
  -X PUT \
  -F 'hexcode=fffeee'
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "hexcode": "#abc123"
}

Update text editor preference

UsersController#set_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:

Parameter	Type	Description
text_editor_preference	string	The identifier for the editor. Allowed values: block_editor, rce, ``

Example Request:

curl 'https://<canvas>/api/v1/users/<user_id>/prefered_editor \
  -X PUT \
  -F 'text_editor_preference=rce'
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "text_editor_preference": "rce"
}

Get dashboard positions

UsersController#get_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:

curl 'https://<canvas>/api/v1/users/<user_id>/dashboard_positions/ \
  -X GET \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "dashboard_positions": {
    "course_42": 2,
    "course_88": 1
  }
}

Update dashboard positions

UsersController#set_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:

curl 'https://<canvas>/api/v1/users/<user_id>/dashboard_positions/ \
  -X PUT \
  -F 'dashboard_positions[course_42]=1' \
  -F 'dashboard_positions[course_53]=2' \
  -F 'dashboard_positions[course_10]=3' \
  -H 'Authorization: Bearer <token>'

Example Response:

{
  "dashboard_positions": {
    "course_10": 3,
    "course_42": 1,
    "course_53": 2
  }
}

Edit a user

UsersController#update

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:

Parameter	Type	Description
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

Example Request: