# Group Categories

{% hint style="warning" %}
**Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)).
{% endhint %}

## Group Categories API

Group Categories allow grouping of groups together in canvas. There are a few different built-in group categories used, or custom ones can be created. The built in group categories are: "communities", "student\_organized", and "imported".

**A GroupCategory object looks like:**

```js
{
  // The ID of the group category.
  "id": 17,
  // The display name of the group category.
  "name": "Math Groups",
  // Certain types of group categories have special role designations. Currently,
  // these include: 'communities', 'student_organized', and 'imported'. Regular
  // course/account group categories have a role of null.
  "role": "communities",
  // If the group category allows users to join a group themselves, thought they
  // may only be a member of one group per group category at a time. Values
  // include 'restricted', 'enabled', and null 'enabled' allows students to assign
  // themselves to a group 'restricted' restricts them to only joining a group in
  // their section null disallows students from joining groups
  "self_signup": null,
  // Gives instructors the ability to automatically have group leaders assigned. 
  // Values include 'random', 'first', and null; 'random' picks a student from the
  // group at random as the leader, 'first' sets the first student to be assigned
  // to the group as the leader
  "auto_leader": null,
  // The course or account that the category group belongs to. The pattern here is
  // that whatever the context_type is, there will be an _id field named after
  // that type. So if instead context_type was 'Course', the course_id field would
  // be replaced by an course_id field.
  "context_type": "Account",
  "account_id": 3,
  // If self-signup is enabled, group_limit can be set to cap the number of users
  // in each group. If null, there is no limit.
  "group_limit": null,
  // The SIS identifier for the group category. This field is only included if the
  // user has permission to manage or view SIS information.
  "sis_group_category_id": null,
  // The unique identifier for the SIS import. This field is only included if the
  // user has permission to manage SIS information.
  "sis_import_id": null,
  // If the group category has not yet finished a randomly student assignment
  // request, a progress object will be attached, which will contain information
  // related to the progress of the assignment request. Refer to the Progress API
  // for more information
  "progress": null,
  // Indicates whether this group category is non-collaborative. A value of true
  // means these group categories rely on the manage_tags permissions and do not
  // have collaborative features
  "non_collaborative": null
}
```

### [List group categories for a context](#method.group_categories.index) <a href="#method.group_categories.index" id="method.group_categories.index"></a>

[GroupCategoriesController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`GET /api/v1/accounts/:account_id/group_categories`**

**Scope:** `url:GET|/api/v1/accounts/:account_id/group_categories`

**`GET /api/v1/courses/:course_id/group_categories`**

**Scope:** `url:GET|/api/v1/courses/:course_id/group_categories`

Returns a paginated list of group categories in a context. The list returned depends on the permissions of the current user and the specified collaboration state.

**Request Parameters:**

| Parameter             | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `collaboration_state` | `string` | <p>Filter group categories by their collaboration state:</p><p><br></p><ul><li><p><br></p><p>“all”: Return both collaborative and non-collaborative group categories</p><p><br></p></li><li><p><br></p><p>“collaborative”: Return only collaborative group categories (default)</p><p><br></p></li><li><p><br></p><p>“non\_collaborative”: Return only non-collaborative group categories</p><p><br></p></li></ul> |

**Example Request:**

```bash
curl https://<canvas>/api/v1/accounts/<account_id>/group_categories \
     -H 'Authorization: Bearer <token>' \
     -d 'collaboration_state=all'
```

Returns a list of [GroupCategory](#groupcategory) objects.

### [Get a single group category](#method.group_categories.show) <a href="#method.group_categories.show" id="method.group_categories.show"></a>

[GroupCategoriesController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`GET /api/v1/group_categories/:group_category_id`**

**Scope:** `url:GET|/api/v1/group_categories/:group_category_id`

Returns the data for a single group category, or a 401 if the caller doesn’t have the rights to see it.

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/<group_category_id> \
     -H 'Authorization: Bearer <token>'
```

Returns a [GroupCategory](#groupcategory) object.

### [Create a Group Category](#method.group_categories.create) <a href="#method.group_categories.create" id="method.group_categories.create"></a>

[GroupCategoriesController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`POST /api/v1/accounts/:account_id/group_categories`**

**Scope:** `url:POST|/api/v1/accounts/:account_id/group_categories`

**`POST /api/v1/courses/:course_id/group_categories`**

**Scope:** `url:POST|/api/v1/courses/:course_id/group_categories`

Create a new group category

**Request Parameters:**

| Parameter               | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                  | Required `string` | Name of the group category                                                                                                                                                                                                                                                                                                                                                                                |
| `non_collaborative`     | `boolean`         | <p>Can only be set by users with the Differentiation Tag - Add permission</p><p><br></p><p>If set to true, groups in this category will be only be visible to users with the Differentiation Tag - Manage permission.</p>                                                                                                                                                                                 |
| `self_signup`           | `string`          | <p>Allow students to sign up for a group themselves (Course Only). valid values are:</p><p><br></p><ul><li><p>“enabled”</p><p>allows students to self sign up for any group in course</p></li><li><p>“restricted”</p><p>allows students to self sign up only for groups in the same section null disallows self sign up</p></li></ul><p>Allowed values: <code>enabled</code>, <code>restricted</code></p> |
| `auto_leader`           | `string`          | <p>Assigns group leaders automatically when generating and allocating students to groups Valid values are:</p><p><br></p><ul><li><p>“first”</p><p>the first student to be allocated to a group is the leader</p></li><li><p>“random”</p><p>a random student from all members is chosen as the leader</p></li></ul><p>Allowed values: <code>first</code>, <code>random</code></p>                          |
| `group_limit`           | `integer`         | Limit the maximum number of users in each group (Course Only). Requires self signup.                                                                                                                                                                                                                                                                                                                      |
| `sis_group_category_id` | `string`          | The unique SIS identifier.                                                                                                                                                                                                                                                                                                                                                                                |
| `create_group_count`    | `integer`         | Create this number of groups (Course Only).                                                                                                                                                                                                                                                                                                                                                               |
| `split_group_count`     | `string`          | (Deprecated) Create this number of groups, and evenly distribute students among them. not allowed with “enable\_self\_signup”. because the group assignment happens synchronously, it’s recommended that you instead use the assign\_unassigned\_members endpoint. (Course Only)                                                                                                                          |

**Example Request:**

```bash
curl htps://<canvas>/api/v1/courses/<course_id>/group_categories \
    -F 'name=Project Groups' \
    -H 'Authorization: Bearer <token>'
```

Returns a [GroupCategory](#groupcategory) object.

### [Bulk manage differentiation tags](#method.group_categories.bulk_manage_differentiation_tag) <a href="#method.group_categories.bulk_manage_differentiation_tag" id="method.group_categories.bulk_manage_differentiation_tag"></a>

[GroupCategoriesController#bulk\_manage\_differentiation\_tag](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`POST /api/v1/courses/:course_id/group_categories/bulk_manage_differentiation_tag`**

**Scope:** `url:POST|/api/v1/courses/:course_id/group_categories/bulk_manage_differentiation_tag`

This API is only meant for Groups and GroupCategories where non\_collaborative is true.

Perform bulk operations on groups within a group category, or create a new group category along with the groups in one transaction. If creation of the GroupCategory or any Group fails, the entire operation will be rolled back.

**Request Parameters:**

<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>operations</code></td><td>Required <code>Hash</code></td><td><p>A hash containing arrays of create/update/delete operations: {</p><p><br></p><pre><code>"create": [
  { "name": "New Group A" },
  { "name": "New Group B" }
],
"update": [
  { "id": 123, "name": "Updated Group Name A" },
  { "id": 456, "name": "Updated Group Name B" }
],
"delete": [
  { "id": 789 },
  { "id": 101 }
]
</code></pre><p><br></p><p>}</p></td></tr><tr><td><code>group_category</code></td><td>Required <code>Hash</code></td><td><p>Attributes for the GroupCategory. May include:</p><p><br></p><pre><code>- id [Optional, Integer]: The ID of an existing GroupCategory.
- name [Optional, String]: A new name for the GroupCategory. If provided with an ID, the category name will be updated.
</code></pre></td></tr></tbody></table>

**Example Request:**

```bash
curl https://<canvas>/api/v1/courses/:course_id/group_categories/bulk_manage_differentiation_tag \
     -X POST \
     -H 'Authorization: Bearer <token>' \
     -H 'Content-Type: application/json' \
     -d '{
           "operations": {
             "create": [{"name": "New Group"}],
             "update": [{"id": 123, "name": "Updated Group"}],
             "delete": [{"id": 456}]
           },
           "group_category": {"id": 1, "name": "New Category Name"}
         }'
```

### [Import differentiation tags](#method.group_categories.import_tags) <a href="#method.group_categories.import_tags" id="method.group_categories.import_tags"></a>

[GroupCategoriesController#import\_tags](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`POST /api/v1/courses/:course_id/group_categories/import_tags`**

**Scope:** `url:POST|/api/v1/courses/:course_id/group_categories/import_tags`

Create Differentiation Tags through a CSV import

For more information on the format that’s expected here, please see the “Differentiation Tag CSV” section in the API docs.

**Request Parameters:**

<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>attachment</code></td><td><code>string</code></td><td><p>There are two ways to post differentiation tag import data - either via a multipart/form-data form-field-style attachment, or via a non-multipart raw post request.</p><p><br></p><p>‘attachment’ is required for multipart/form-data style posts. Assumed to be tag data from a file upload form field named ‘attachment’.</p><p><br></p><p>Examples:</p><p><br></p><pre><code>curl -F attachment=@&#x3C;filename> -H "Authorization: Bearer &#x3C;token>" &#x3C;br>    'https://&#x3C;canvas>/api/v1/group_categories/import_tags'
</code></pre><p><br></p><p>If you decide to do a raw post, you can skip the ‘attachment’ argument, but you will then be required to provide a suitable Content-Type header. You are encouraged to also provide the ‘extension’ argument.</p><p><br></p><p>Examples:</p><p><br></p><pre><code>curl -H 'Content-Type: text/csv' --data-binary @&#x3C;filename>.csv &#x3C;br>    -H "Authorization: Bearer &#x3C;token>" &#x3C;br>    'https://&#x3C;canvas>/api/v1/group_categories_tags'
</code></pre></td></tr></tbody></table>

**Example Response:**

```js
# Progress (default)
{
    "completion": 0,
    "context_id": 20,
    "context_type": "Course",
    "created_at": "2013-07-05T10:57:48-06:00",
    "id": 2,
    "message": null,
    "tag": "course_tag_import",
    "updated_at": "2013-07-05T10:57:48-06:00",
    "user_id": null,
    "workflow_state": "running",
    "url": "http://localhost:3000/api/v1/progress/2"
}
```

Returns a [Progress](https://developerdocs.instructure.com/services/canvas/progress#progress) object.

### [Import category groups](#method.group_categories.import) <a href="#method.group_categories.import" id="method.group_categories.import"></a>

[GroupCategoriesController#import](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`POST /api/v1/group_categories/:group_category_id/import`**

**Scope:** `url:POST|/api/v1/group_categories/:group_category_id/import`

Create Groups in a Group Category through a CSV import

For more information on the format that’s expected here, please see the “Group Category CSV” section in the API docs.

**Request Parameters:**

<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>attachment</code></td><td><code>string</code></td><td><p>There are two ways to post group category import data - either via a multipart/form-data form-field-style attachment, or via a non-multipart raw post request.</p><p><br></p><p>‘attachment’ is required for multipart/form-data style posts. Assumed to be outcome data from a file upload form field named ‘attachment’.</p><p><br></p><p>Examples:</p><p><br></p><pre><code>curl -F attachment=@&#x3C;filename> -H "Authorization: Bearer &#x3C;token>" &#x3C;br>    'https://&#x3C;canvas>/api/v1/group_categories/&#x3C;category_id>/import'
</code></pre><p><br></p><p>If you decide to do a raw post, you can skip the ‘attachment’ argument, but you will then be required to provide a suitable Content-Type header. You are encouraged to also provide the ‘extension’ argument.</p><p><br></p><p>Examples:</p><p><br></p><pre><code>curl -H 'Content-Type: text/csv' --data-binary @&#x3C;filename>.csv &#x3C;br>    -H "Authorization: Bearer &#x3C;token>" &#x3C;br>    'https://&#x3C;canvas>/api/v1/group_categories/&#x3C;category_id>/import'
</code></pre></td></tr></tbody></table>

**Example Response:**

```js
# Progress (default)
{
    "completion": 0,
    "context_id": 20,
    "context_type": "GroupCategory",
    "created_at": "2013-07-05T10:57:48-06:00",
    "id": 2,
    "message": null,
    "tag": "course_group_import",
    "updated_at": "2013-07-05T10:57:48-06:00",
    "user_id": null,
    "workflow_state": "running",
    "url": "http://localhost:3000/api/v1/progress/2"
}
```

Returns a [Progress](https://developerdocs.instructure.com/services/canvas/progress#progress) object.

### [Update a Group Category](#method.group_categories.update) <a href="#method.group_categories.update" id="method.group_categories.update"></a>

[GroupCategoriesController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`PUT /api/v1/group_categories/:group_category_id`**

**Scope:** `url:PUT|/api/v1/group_categories/:group_category_id`

Modifies an existing group category.

**Request Parameters:**

| Parameter               | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                  | `string`  | Name of the group category                                                                                                                                                                                                                                                                                                                                                                                |
| `self_signup`           | `string`  | <p>Allow students to sign up for a group themselves (Course Only). Valid values are:</p><p><br></p><ul><li><p>“enabled”</p><p>allows students to self sign up for any group in course</p></li><li><p>“restricted”</p><p>allows students to self sign up only for groups in the same section null disallows self sign up</p></li></ul><p>Allowed values: <code>enabled</code>, <code>restricted</code></p> |
| `auto_leader`           | `string`  | <p>Assigns group leaders automatically when generating and allocating students to groups Valid values are:</p><p><br></p><ul><li><p>“first”</p><p>the first student to be allocated to a group is the leader</p></li><li><p>“random”</p><p>a random student from all members is chosen as the leader</p></li></ul><p>Allowed values: <code>first</code>, <code>random</code></p>                          |
| `group_limit`           | `integer` | Limit the maximum number of users in each group (Course Only). Requires self signup.                                                                                                                                                                                                                                                                                                                      |
| `sis_group_category_id` | `string`  | The unique SIS identifier.                                                                                                                                                                                                                                                                                                                                                                                |
| `create_group_count`    | `integer` | Create this number of groups (Course Only).                                                                                                                                                                                                                                                                                                                                                               |
| `split_group_count`     | `string`  | (Deprecated) Create this number of groups, and evenly distribute students among them. not allowed with “enable\_self\_signup”. because the group assignment happens synchronously, it’s recommended that you instead use the assign\_unassigned\_members endpoint. (Course Only)                                                                                                                          |

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/<group_category_id> \
    -X PUT \
    -F 'name=Project Groups' \
    -H 'Authorization: Bearer <token>'
```

Returns a [GroupCategory](#groupcategory) object.

### [Delete a Group Category](#method.group_categories.destroy) <a href="#method.group_categories.destroy" id="method.group_categories.destroy"></a>

[GroupCategoriesController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`DELETE /api/v1/group_categories/:group_category_id`**

**Scope:** `url:DELETE|/api/v1/group_categories/:group_category_id`

Deletes a group category and all groups under it. Protected group categories can not be deleted, i.e. “communities” and “student\_organized”.

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/<group_category_id> \
      -X DELETE \
      -H 'Authorization: Bearer <token>'
```

### [List groups in group category](#method.group_categories.groups) <a href="#method.group_categories.groups" id="method.group_categories.groups"></a>

[GroupCategoriesController#groups](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`GET /api/v1/group_categories/:group_category_id/groups`**

**Scope:** `url:GET|/api/v1/group_categories/:group_category_id/groups`

Returns a paginated list of groups in a group category

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/<group_cateogry_id>/groups \
     -H 'Authorization: Bearer <token>'
```

Returns a list of [Group](https://developerdocs.instructure.com/services/canvas/groups#group) objects.

### [export groups in and users in category](#method.group_categories.export) <a href="#method.group_categories.export" id="method.group_categories.export"></a>

[GroupCategoriesController#export](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

{% hint style="warning" %}
BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.
{% endhint %}

**`GET /api/v1/group_categories/:group_category_id/export`**

**Scope:** `url:GET|/api/v1/group_categories/:group_category_id/export`

Returns a csv file of users in format ready to import.

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/<group_category_id>/export \
     -H 'Authorization: Bearer <token>'
```

### [export tags and users in course](#method.group_categories.export_tags) <a href="#method.group_categories.export_tags" id="method.group_categories.export_tags"></a>

[GroupCategoriesController#export\_tags](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

{% hint style="warning" %}
BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.
{% endhint %}

**`GET /api/v1/courses/:course_id/group_categories/export_tags`**

**Scope:** `url:GET|/api/v1/courses/:course_id/group_categories/export_tags`

Returns a csv file of users in format ready to import.

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/export_tags \
     -H 'Authorization: Bearer <token>'
```

### [List users in group category](#method.group_categories.users) <a href="#method.group_categories.users" id="method.group_categories.users"></a>

[GroupCategoriesController#users](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`GET /api/v1/group_categories/:group_category_id/users`**

**Scope:** `url:GET|/api/v1/group_categories/:group_category_id/users`

Returns a paginated list of users in the group category.

**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. |
| `unassigned`  | `boolean` | Set this value to true if you wish only to search unassigned users in the group category.                        |

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/1/users \
     -H 'Authorization: Bearer <token>'
```

Returns a list of [User](https://developerdocs.instructure.com/services/canvas/users#user) objects.

### [Assign unassigned members](#method.group_categories.assign_unassigned_members) <a href="#method.group_categories.assign_unassigned_members" id="method.group_categories.assign_unassigned_members"></a>

[GroupCategoriesController#assign\_unassigned\_members](https://github.com/instructure/canvas-lms/blob/master/app/controllers/group_categories_controller.rb)

**`POST /api/v1/group_categories/:group_category_id/assign_unassigned_members`**

**Scope:** `url:POST|/api/v1/group_categories/:group_category_id/assign_unassigned_members`

Assign all unassigned members as evenly as possible among the existing student groups.

**Request Parameters:**

| Parameter | Type      | Description                                                                                                                                            |
| --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sync`    | `boolean` | The assigning is done asynchronously by default. If you would like to override this and have the assigning done synchronously, set this value to true. |

**Example Request:**

```bash
curl https://<canvas>/api/v1/group_categories/1/assign_unassigned_members \
     -H 'Authorization: Bearer <token>'
```

**Example Response:**

```js
# Progress (default)
{
    "completion": 0,
    "context_id": 20,
    "context_type": "GroupCategory",
    "created_at": "2013-07-05T10:57:48-06:00",
    "id": 2,
    "message": null,
    "tag": "assign_unassigned_members",
    "updated_at": "2013-07-05T10:57:48-06:00",
    "user_id": null,
    "workflow_state": "running",
    "url": "http://localhost:3000/api/v1/progress/2"
}
```

```js
# New Group Memberships (when sync = true)
[
  {
    "id": 65,
    "new_members": [
      {
        "user_id": 2,
        "name": "Sam",
        "display_name": "Sam",
        "sections": [
          {
            "section_id": 1,
            "section_code": "Section 1"
          }
        ]
      },
      {
        "user_id": 3,
        "name": "Sue",
        "display_name": "Sue",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      }
    ]
  },
  {
    "id": 66,
    "new_members": [
      {
        "user_id": 5,
        "name": "Joe",
        "display_name": "Joe",
        "sections": [
          {
            "section_id": 2,
            "section_code": "Section 2"
          }
        ]
      },
      {
        "user_id": 11,
        "name": "Cecil",
        "display_name": "Cecil",
        "sections": [
          {
            "section_id": 3,
            "section_code": "Section 3"
          }
        ]
      }
    ]
  }
]
```

***

This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developerdocs.instructure.com/services/canvas/resources/group_categories.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.