Accounts API

List accounts AccountsController#index

GET /api/v1/accounts

List 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.

Get a single account AccountsController#show

GET /api/v1/accounts/:id

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

Get the sub-accounts of an account AccountsController#sub_accounts

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

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

Request Parameters:

  • recursive
    optional

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

List active courses in an account AccountsController#courses_api

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

Retrieve the list of courses in this account.

Request Parameters:

  • with_enrollments
    optional

    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.

  • published
    optional

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

  • completed
    optional

    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.

  • by_teachers[]
    optional

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

  • by_subaccounts[]
    optional

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

  • hide_enrollmentless_courses
    optional

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

  • state[]
    optional

    If set, only return courses that are in the given state(s). Valid states are "created," "claimed," "available," "completed," and "deleted." By default, all states but "deleted" are returned.

Returns a list of Courses

Update an account AccountsController#update

PUT /api/v1/accounts/:id

Update an existing account.

Request Parameters:

  • account[name]
    optional

    Updates the account name

  • account[default_time_zone]
    Optional

    The default time zone of the account. Allowed time zones are listed in The Ruby on Rails documentation.

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

Example Response:

{
  "id": "1",
  "name": "New account name",
  "default_time_zone": "Mountain Time (US & Canada)",
  "parent_account_id": null,
  "root_account_id": null
}