> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/canvas/group-categories/file.group_category_csv.md).

# Group Categories CSV Format

## Group Category Import Format Documentation

Group categories can be updated in bulk by using the Group Categories Import API. Each row in a CSV file represents a user to be added to a group in the group category.

Groups that don't exist in the UI will be created. Groups that are created will only use the group\_name column for creation. User columns in the file are used to identify the user to be added to the group. Users names are available in the group\_category export, but not used or updated in the import process.

Standard CSV rules apply (including adherence to the CSV RFC 4180 format):

* The first row will be interpreted as a header defining the ordering of your columns. This header row is mandatory.
* Fields that contain a comma must be surrounded by double-quotes.
* Fields that contain double-quotes must also be surrounded by double-quotes, with the internal double-quotes doubled. Example: Chevy "The Man" Chase would be included in the CSV as "Chevy ""The Man"" Chase".

All text should be UTF-8 encoded.

## Group Category Data Format

### group\_category.csv

| Field Name        | Data Type | Required | Description                                                                                                                                                                                                                         |
| ----------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| canvas\_user\_id  | text      | ✓\*      | The canvas id for a user, required to identify a user.                                                                                                                                                                              |
| user\_id          | text      | ✓\*      | A unique identifier used to reference users in the enrollments table. This identifier must not change for the user, and must be globally unique. In the user interface, this is called the SIS ID.                                  |
| login\_id         | text      | ✓\*      | The name that a user will use to login to Instructure. If you have an authentication service configured (like LDAP), this will be their username from the remote system.                                                            |
| group\_name       | text      | ✓\*      | The name of the group.                                                                                                                                                                                                              |
| canvas\_group\_id | text      | ✓\*      | The canvas id for a group.                                                                                                                                                                                                          |
| group\_id         | text      | ✓\*      | A unique identifier used to reference groups in the group\_users data. This identifier must not change for the group, and must be globally unique. This column is for identification and does not populate new groups with sis\_ids |

\* canvas\_user\_id, user\_id, or login\_id is required and group\_name, canvas\_group\_id or group\_id is required.

Sample:

```
canvas_user_id,user_id,login_id,group_name,canvas_group_id,group_id
92,,,Awesome Group,,
,13aa3,,,45,
,,mlemon,,,g125
```

```
canvas_user_id,user_id,login_id,group_name
92,,,Awesome Group
,13aa3,,Other Group
,,mlemon,Awesome Group
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developerdocs.instructure.com/services/canvas/group-categories/file.group_category_csv.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
