Accounts API

API for accessing account data.

An Account object looks like:

{
  // the ID of the Account object
  "id": 2,
  // The display name of the account
  "name": "Canvas Account",
  // The UUID of the account
  "uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5",
  // The account's parent ID, or null if this is the root account
  "parent_account_id": 1,
  // The ID of the root account, or null if this is the root account
  "root_account_id": 1,
  // The storage quota for the account in megabytes, if not otherwise specified
  "default_storage_quota_mb": 500,
  // The storage quota for a user in the account in megabytes, if not otherwise
  // specified
  "default_user_storage_quota_mb": 50,
  // The storage quota for a group in the account in megabytes, if not otherwise
  // specified
  "default_group_storage_quota_mb": 50,
  // The default time zone of the account. Allowed time zones are
  // {http://www.iana.org/time-zones IANA time zones} or friendlier
  // {http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html Ruby on Rails
  // time zones}.
  "default_time_zone": "America/Denver",
  // The account's identifier in the Student Information System. Only included if the
  // user has permission to view SIS information.
  "sis_account_id": "123xyz",
  // The account's identifier in the Student Information System. Only included if the
  // user has permission to view SIS information.
  "integration_id": "123xyz",
  // The id of the SIS import if created through SIS. Only included if the user has
  // permission to manage SIS information.
  "sis_import_id": 12,
  // The account's identifier that is sent as context_id in LTI launches.
  "lti_guid": "123xyz",
  // The state of the account. Can be 'active' or 'deleted'.
  "workflow_state": "active"
}

List accounts AccountsController#index

GET /api/v1/accounts

Scope: url:GET|/api/v1/accounts

A paginated list of accounts that the current user can view or manage. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in.

Request Parameters:

Parameter Type Description
include[] string

Array of additional information to include.

“lti_guid”

the 'tool_consumer_instance_guid' that will be sent for this account on LTI launches

“registration_settings”

returns info about the privacy policy and terms of use

“services”

returns services and whether they are enabled (requires account management permissions)

Allowed values: lti_guid, registration_settings, services

Returns a list of Accounts

List accounts for course admins AccountsController#course_accounts

GET /api/v1/course_accounts

Scope: url:GET|/api/v1/course_accounts

A paginated list of accounts that the current user can view through their admin course enrollments. (Teacher, TA, or designer enrollments). Only returns “id”, “name”, “workflow_state”, “root_account_id” and “parent_account_id”

Returns a list of Accounts

Get a single account AccountsController#show

GET /api/v1/accounts/:id

Scope: url:GET|/api/v1/accounts/:id

Retrieve information on an individual account, given by id or sis sis_account_id.

Returns a Account

Permissions AccountsController#permissions

GET /api/v1/accounts/:account_id/permissions

Scope: url:GET|/api/v1/accounts/:account_id/permissions

Returns permission information for the calling user and the given account. You may use `self` as the account id to check permissions against the domain root account. The caller must have an account role or admin (teacher/TA/designer) enrollment in a course in the account. See also the Course counterpart.

Request Parameters:

Parameter Type Description
permissions[] string

List of permissions to check against the authenticated user. Permission names are documented in the Create a role endpoint.

Example Request:

curl https://<canvas>/api/v1/accounts/self/permissions \
  -H 'Authorization: Bearer <token>' \
  -d 'permissions[]=manage_account_memberships' \
  -d 'permissions[]=become_user'

Example Response:

{'manage_account_memberships': 'false', 'become_user': 'true'}

Get the sub-accounts of an account AccountsController#sub_accounts

GET /api/v1/accounts/:account_id/sub_accounts

Scope: url:GET|/api/v1/accounts/:account_id/sub_accounts

List accounts that are sub-accounts of the given account.

Request Parameters:

Parameter Type Description
recursive boolean

If true, the entire account tree underneath this account will be returned (though still paginated). If false, only direct sub-accounts of this account will be returned. Defaults to false.

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id>/sub_accounts \
     -H 'Authorization: Bearer <token>'
Returns a list of Accounts

Returns the terms of service for that account AccountsController#terms_of_service

GET /api/v1/accounts/:account_id/terms_of_service

Scope: url:GET|/api/v1/accounts/:account_id/terms_of_service

List active courses in an account AccountsController#courses_api

GET /api/v1/accounts/:account_id/courses

Scope: url:GET|/api/v1/accounts/:account_id/courses

Retrieve a paginated list of courses in this account.

Request Parameters:

Parameter Type Description
with_enrollments boolean

If true, include only courses with at least one enrollment. If false, include only courses with no enrollments. If not present, do not filter on course enrollment status.
enrollment_type[] string

If set, only return courses that have at least one user enrolled in in the course with one of the specified enrollment types.

Allowed values: teacher, student, ta, observer, designer

published boolean

If true, include only published courses. If false, exclude published courses. If not present, do not filter on published status.
completed boolean

If true, include only completed courses (these may be in state 'completed', or their enrollment term may have ended). If false, exclude completed courses. If not present, do not filter on completed status.
blueprint boolean

If true, include only blueprint courses. If false, exclude them. If not present, do not filter on this basis.
blueprint_associated boolean

If true, include only courses that inherit content from a blueprint course. If false, exclude them. If not present, do not filter on this basis.
by_teachers[] integer

List of User IDs of teachers; if supplied, include only courses taught by one of the referenced users.
by_subaccounts[] integer

List of Account IDs; if supplied, include only courses associated with one of the referenced subaccounts.
hide_enrollmentless_courses boolean

If present, only return courses that have at least one enrollment. Equivalent to 'with_enrollments=true'; retained for compatibility.
state[] string

If set, only return courses that are in the given state(s). By default, all states but “deleted” are returned.

Allowed values: created, claimed, available, completed, deleted, all

enrollment_term_id integer

If set, only includes courses from the specified term.
search_term string

The partial course name, code, or full ID to match and return in the results list. Must be at least 3 characters.
include[] string

  • All explanations can be seen in the Course API index documentation

  • “sections”, “needs_grading_count” and “total_scores” are not valid options at the account level

Allowed values: syllabus_body, term, course_progress, storage_quota_used_mb, total_students, teachers, account_name

sort string

The column to sort results by.

Allowed values: course_name, sis_course_id, teacher, account_name

order string

The order to sort the given column by.

Allowed values: asc, desc

search_by string

The filter to search by. “course” searches for course names, course codes, and SIS IDs. “teacher” searches for teacher names

Allowed values: course, teacher

Returns a list of Courses

Update an account AccountsController#update

PUT /api/v1/accounts/:id

Scope: url:PUT|/api/v1/accounts/:id

Update an existing account.

Request Parameters:

Parameter Type Description
account[name] string

Updates the account name
account[sis_account_id] string

Updates the account sis_account_id Must have manage_sis permission and must not be a root_account.
account[default_time_zone] string

The default time zone of the account. Allowed time zones are IANA time zones or friendlier Ruby on Rails time zones.
account[default_storage_quota_mb] integer

The default course storage quota to be used, if not otherwise specified.
account[default_user_storage_quota_mb] integer

The default user storage quota to be used, if not otherwise specified.
account[default_group_storage_quota_mb] integer

The default group storage quota to be used, if not otherwise specified.
account[settings][restrict_student_past_view][value] boolean

Restrict students from viewing courses after end date
account[settings][restrict_student_past_view][locked] boolean

Lock this setting for sub-accounts and courses
account[settings][restrict_student_future_view][value] boolean

Restrict students from viewing courses before start date
account[settings][restrict_student_future_view][locked] boolean

Lock this setting for sub-accounts and courses
account[settings][lock_all_announcements][value] boolean

Disable comments on announcements
account[settings][lock_all_announcements][locked] boolean

Lock this setting for sub-accounts and courses
account[settings][restrict_student_future_listing][value] boolean

Restrict students from viewing future enrollments in course list
account[settings][restrict_student_future_listing][locked] boolean

Lock this setting for sub-accounts and courses
account[services] Hash

Give this a set of keys and boolean values to enable or disable services matching the keys

Example Request:

curl https://<canvas>/api/v1/accounts/<account_id> \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'account[name]=New account name' \
  -d 'account[default_time_zone]=Mountain Time (US & Canada)' \
  -d 'account[default_storage_quota_mb]=450'
Returns a Account

Delete a user from the root account AccountsController#remove_user

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

Scope: url:DELETE|/api/v1/accounts/:account_id/users/:user_id

Delete a user record from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts.

WARNING: This API will allow a user to remove themselves from the account. If they do this, they won't be able to make API calls or log into Canvas at that account.

Example Request:

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

Create a new sub-account SubAccountsController#create

POST /api/v1/accounts/:account_id/sub_accounts

Scope: url:POST|/api/v1/accounts/:account_id/sub_accounts

Add a new sub-account to a given account.

Request Parameters:

Parameter Type Description
account[name] Required string

The name of the new sub-account.
account[sis_account_id] string

The account's identifier in the Student Information System.
account[default_storage_quota_mb] integer

The default course storage quota to be used, if not otherwise specified.
account[default_user_storage_quota_mb] integer

The default user storage quota to be used, if not otherwise specified.
account[default_group_storage_quota_mb] integer

The default group storage quota to be used, if not otherwise specified.
Returns a Account

Delete a sub-account SubAccountsController#destroy

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

Scope: url:DELETE|/api/v1/accounts/:account_id/sub_accounts/:id

Cannot delete an account with active courses or active sub_accounts. Cannot delete a root_account

Returns a Account