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": "sheldon@caltech.example.com",
  // 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": "sheldon@caltech.example.com",
  // 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",
  // sample_user@example.com
  "primary_email": "sample_user@example.com",
  // sample_user@example.com
  "login_id": "sample_user@example.com",
  // 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}
}
// 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"
}

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.

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

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
  }
]

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,
  },
]

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
}

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"
  }
]

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.

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
}

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
}

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.

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.

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.

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.

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

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"
  }
}

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"
}

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"
}

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"
}

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
  }
}

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
  }
}

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: