Users API

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.

An User object looks like:

{
  // The ID of the user.
  "id": 1,

  // 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",

  // 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
  "sis_user_id": "",

  // DEPRECATED: The SIS login ID associated with the user. Please use the
  // sis_user_id or login_id. This field will be removed in a future version of
  // the API.
  "sis_login_id": "",

  // 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": "",

  // 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": [
    // ...
  ],

  // 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.
  "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 ceratin API calls, and will
  // return the IANA time zone name of
  // the user's preferred timezone
  "time_zone": "America/Denver",
}

List users UsersController#index

GET /api/v1/accounts/:account_id/users

Retrieve the list of users associated with this account.

Request Parameters:

  • search_term

    (optional) The partial name or full ID of the users to match and return in the results list. Must be at least 3 characters.

Returns a list of Users

List the activity stream UsersController#activity_stream

GET /api/v1/users/self/activity_stream

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

CollectionItem:

{
  'type': 'CollectionItem',
  'collection_item' { ... full CollectionItem data ... }
}

Activity stream summary UsersController#activity_stream_summary

GET /api/v1/users/self/activity_stream/summary

Returns a summary of the current user's global activity stream.

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

Returns the current user's list of todo items, as seen on the user dashboard.

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.

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

List upcoming assignments, calendar events UsersController#upcoming_events

GET /api/v1/users/self/upcoming_events

Returns the current user's upcoming events, i.e. the same things shown in the dashboard 'Coming Up' sidebar.

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"],
      "muted"=>false,
      "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"
  }
]

Upload a file UsersController#create_file

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.

Create a user UsersController#create

POST /api/v1/accounts/:account_id/users

Create and return a new user and pseudonym for an account.

Request Parameters:

  • user[name]
    Optional

    The full name of the user. This name will be used by teacher for grading.

  • user[short_name]
    Optional

    User's name as it will be displayed in discussions, messages, and comments.

  • user[sortable_name]
    Optional

    User's name as used to sort alphabetically in lists.

  • user[time_zone]
    Optional

    The time zone for the user. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

  • user[locale]
    Optional

    The user's preferred language as a two-letter ISO 639-1 code.

  • user[birthdate]
    Optional

    The user's birth date.

  • pseudonym[unique_id]

    User's login ID.

  • pseudonym[password]
    Optional

    User's password.

  • pseudonym[sis_user_id]
    Optional
    Integer

    SIS ID for the user's account. To set this parameter, the caller must be able to manage SIS permissions.

  • pseudonym[send_confirmation]
    Optional, 0|1
    Integer

    Send user notification of account creation if set to 1.

  • communication_channel[type]
    Optional

    The communication channel type, e.g. 'email' or 'sms'.

  • communication_channel[address]
    Optional

    The communication channel address, e.g. the user's email address.

Returns a User

Update user settings. UsersController#settings

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

PUT /api/v1/users/:id/settings

Update an existing user's settings.

Request Parameters:

  • manual_mark_as_read

    If true, require user to manually mark discussion posts as read (don't auto-mark as read).

Example Request:

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

Edit a user UsersController#update

PUT /api/v1/users/:id

Modify an existing user. To modify a user's login, see the documentation for logins.

Request Parameters:

  • user[name]
    Optional

    The full name of the user. This name will be used by teacher for grading.

  • user[short_name]
    Optional

    User's name as it will be displayed in discussions, messages, and comments.

  • user[sortable_name]
    Optional

    User's name as used to sort alphabetically in lists.

  • user[time_zone]
    Optional

    The time zone for the user. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.

  • user[locale]
    Optional

    The user's preferred language as a two-letter ISO 639-1 code.

  • user[avatar][token]
    Optional

    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[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]
    Optional

    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.

Example Request:

curl 'http://<canvas>/api/v1/users/133.json' \ 
     -X PUT \ 
     -F 'user[name]=Sheldon Cooper' \ 
     -F 'user[short_name]=Shelly' \ 
     -F 'user[time_zone]=Pacific Time (US & Canada)' \ 
     -F 'user[avatar][token]=<opaque_token>' \ 
     -H "Authorization: Bearer <token>"
Returns a User

Delete a user UsersController#destroy

DELETE /api/v1/accounts/:account_id/users/:id

Delete a user record from Canvas.

WARNING: This API will allow a user to delete themselves. If you do this, you won't be able to make API calls or log into Canvas.

Example Request:

curl https://<canvas>/api/v1/users/5 \ 
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \ 
  -X DELETE
Returns a User

Follow a user UsersController#follow

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

PUT /api/v1/users/:user_id/followers/self

Follow this user. If the current user is already following the target user, nothing happens. The target user must have a public profile in order to follow it.

On success, returns the User object. Responds with a 401 if the user doesn't have permission to follow the target user, or a 400 if the user can't follow the target user (if the user and target user are the same, for example).

Example Request:

curl https://<canvas>/api/v1/users/<user_id>/followers/self \ 
     -X PUT \ 
     -H 'Content-Length: 0' \ 
     -H 'Authorization: Bearer <token>'

Example Response:

{
  following_user_id: 5,
  followed_user_id: 6,
  created_at: <timestamp>
}

Un-follow a user UsersController#unfollow

BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.

DELETE /api/v1/users/:user_id/followers/self

Stop following this user. If the current user is not already following the target user, nothing happens.

Example Request:

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

Get user profile ProfileController#settings

GET /api/v1/users/:user_id/profile

Returns user profile data, including user id, name, and profile pic.

When requesting the profile for the user accessing the API, the user's calendar feed URL will be returned as well.

Example Response:

{
  'id': 1234,
  'name': 'Sample User',
  'short_name': 'Sample User'
  'sortable_name': 'user, sample',
  'primary_email': 'sample_user@example.com',
  'login_id': 'sample_user@example.com',
  'sis_user_id': 'sis1',
  'sis_login_id': 'sis1-login',
  // The avatar_url can change over time, so we recommend not caching it for more than a few hours
  'avatar_url': '..url..',
  'calendar': { 'ics' => '..url..' },
  'time_zone': 'America/Denver'
}

List avatar options ProfileController#profile_pics

GET /api/v1/users/:user_id/avatars

Retrieve the possible user avatar options that can be set with the user update endpoint. The response will be an array of avatar records. If the 'type' field is 'attachment', the record will include all the normal attachment json fields; otherwise it will include only the 'url' and 'display_name' fields. Additionally, all records will include a 'type' field and a 'token' field. The following explains each field in more detail

type
"gravatar"|"attachment"|"no_pic"

The type of avatar record, for categorization purposes.

url

The url of the avatar

token

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.

display_name

A textual description of the avatar record

id
'attachment' type only

the internal id of the attachment

content-type
'attachment' type only

the content-type of the attachment

filename
'attachment' type only

the filename of the attachment

size
'attachment' type only

the size of the attachment

Example Request:

curl 'http://<canvas>/api/v1/users/1/avatars.json' \ 
     -H "Authorization: Bearer <token>"

Example Response:

[
  {
    "type":"gravatar",
    "url":"https://secure.gravatar.com/avatar/2284...",
    "token":<opaque_token>,
    "display_name":"gravatar pic"
  },
  {
    "type":"attachment",
    "url":"https://<canvas>/images/thumbnails/12/gpLWJ...",
    "token":<opaque_token>,
    "display_name":"profile.jpg",
    "id":12,
    "content-type":"image/jpeg",
    "filename":"profile.jpg",
    "size":32649
  },
  {
    "type":"no_pic",
    "url":"https://<canvas>/images/dotted_pic.png",
    "token":<opaque_token>,
    "display_name":"no pic"
  }
]

List user page views PageViewsController#index

GET /api/v1/users/:user_id/page_views

Return the user's page view history in json format, similar to the available CSV download. Pagination is used as described in API basics section. Page views are returned in descending order, newest to oldest.

Request Parameters:

  • start_time
    Datetime
    optional

    The beginning of the time range

    from which you want page views.

  • end_time
    Datetime
    optional

    The end of the time range

    from which you want page views.

API response field:

  • interaction_seconds

    The number of seconds the user actively interacted with the page. This is a best guess, using heuristics such as browser input events.

  • url

    The full canvas URL of the page view.

  • user_agent

    The browser identifier or other user agent that was used to make the request.

  • controller

    The Rails controller that processed the request.

  • action

    The action in the Rails controller that processed the request.

  • context_type

    The type of "context" of the request, e.g. Account or Course.