How do I format CSV text files for uploading SIS data into a Canvas account?
Canvas allows you to manually bulk create users, accounts, terms, courses, sections, and enrollments through the Admin interface.
This document references the SIS Import CSV Format API page, where the majority of the CSV information is located. Each CSV file is symbiotic with another and tell Canvas how to manage all information for the account. View an SIS relationship diagram.
Each step in this lesson provides sample CSV files with descriptions of each required and optional field. You will also find a link to download each file if you want to take a deeper look at the formatting. Download a zipped package of all sample files.
You should practice importing data in your Canvas test environment before importing any content to your production environment.
CSV File Format
In order to bulk upload data into Canvas, you must create one or more CSV text files. CSV files can be generated by many programs. Student Information Systems (SIS) often have a method for generating reports in CSV format that can be modified to fit the format Canvas requires. If you do not know how to save a file in a CSV format, please check the documentation for the program you are using to create your CSV file (e.g., Excel).
When using the Instructure format for importing files in the SIS Import page, you may import an individual CSV text file or you may compress multiple files into a single ZIP file to bulk import data. If you are manually uploading individual files, the files must be uploaded in the order shown in this lesson.
CSV Field Formatting
The first row of your CSV file (header) must include the complete field name for each file. The order of the columns does not matter but having the rows ordered properly is crucial for files like the accounts.csv. When any of this data is modified in the User Interface (UI), Canvas will set the new values as "sticky." When a new basic upload is performed, the data existing in Canvas will remain "sticky" and any imported data that would attempt to update that data will be ignored. Learn more about sticky fields.
An import can override UI changes only if the proper options are selected when using the SIS Import tool.
CSV files only include a specific set of fields. Canvas contains additional values that are available through each individual API. After running the CSV files for your institution, standard practice for a majority of institutions is to upload all SIS CSV files and then use the Canvas API to update full account and course attributes. For more information, view the Canvas API documentation for Users, Accounts, Terms, Courses, Sections, Enrollments, and Groups. SIS Imports can also be managed using the SIS Imports API.
Users are the people who have user accounts within an institution. The users.csv adds people into the system as generic users. The enrollments.csv will assign a role (teacher, student, etc.) to these users. When a user account is deleted all of their enrollments will also be deleted and they won't be able to log in to their Canvas account. If you still want the user to be able to log in but just not participate or if you want to only delete them from a particular course, then you should leave their user account as active and change their enrollment (in the enrollments.csv) to completed or deleted, respectively.
Download a sample users.csv file with 10 Canvas user accounts.
- *user_id: This is a unique value used to identify anyone with an account in Canvas. This value must not change for the user, and must be unique across all users. In the user interface, this is called the SIS ID and may be comprised of any combination of characters. You can find this SIS ID by visiting any user account and then viewing their Login Information.
- integration_id: This is a secondary unique identifier useful for more complex SIS integrations. This identifier must not change for the user, and must be globally unique.
- *login_id: This is the username one will use to log in to Canvas. If you have an authentication service configured (like LDAP), this will typically match their username in the remote system. Login_id can contain letters, numbers, or the following symbol characters: - _ = + . @
- password: If the account is configured to use LDAP or an SSO protocol, then this isn't required. Otherwise, this is the password for the 'login_id' above. This password must be at least 8 characters.
- ssha_password: Instead of a plain-text password, you can pass a pre-hashed password using the SSHA password generation scheme in this field. While better than passing a plain text password, you should still encourage users to change their password after logging in for the first time. Learn how to generate SSHA passwords.
- first_name: This is the given (first) name of the user.
- last_name: This is the surname (last) name of the user.
- full_name: This is both the given and surname of the user.
- sortable_name: This is the sortable name option in Canvas, usually inferred from the user's name but it can be customized.
- short_name: This is the display name of the user, usually inferred from the user's name but it can be customized.
- email: This is the institution-assigned email address and will also be marked as the default email address for this user account. This email address should still be provided even if it is the same as the user's login_id.
- *status: This is where you can add or remove a user from Canvas. Mark as active to add a user or deleted to remove an existing user.
Email Address Conflicts
Canvas identifies users by email address. When students are added to a course, Canvas attempts to reconcile any email address conflicts when the user first logs in to the course.
Normally email addresses are unique to each student. At times multiple students may share a single email address. When adding students to courses via SIS import, Canvas recognizes when an email address is assigned to more than one student.
- If a new SIS ID is associated with an email address already assigned to an existing SIS ID, Canvas sends an email to the email address.
- When users are added to an account through SIS import, they will not receive an email notification unless the system detects a duplicate user. However, if a user is added or enrolled manually they will receive an email notifying them they have been added or enrolled in a new course. The student sharing an email address will receive a notification that the email address is already in use and is invited to create a new account in Canvas. This process may also apply when adding a user to a course enrollment.
An account is an organization unit within Canvas (e.g., the parent account for an institution). Each account can contain a hierarchy of sub-accounts, such as creating accounts for individual colleges within an institution, or for individual schools within a district. Sub-accounts can also contain multiple sub-accounts, such as when a college subdivides into departments or programs, or a school that subdivides into grade levels or subjects.
Download a sample accounts.csv file with the following sub-accounts:
- 3 sub-accounts within your main/root account. (Arts & Humanities, Business, Math & Science)
- 4 sub-accounts within your Business sub-account. (Accounting, Computer Science, Economics, and Marketing)
- 3 sub-accounts within your Math & Science sub-account. (Biology, Physics, and Statistics)
- 1 sub-account within your Arts & Humanities sub-account. (Visual Arts)
- 2 sub-accounts within your Visual Arts sub-account. (Photography, and Digital Media)
- *account_id: This is a unique identifier used to create a sub-account. The courses.csv file will allow you to assign courses to a particular account id. This unique identifier must not change for the account, and must be globally unique across all accounts. In the Canvas UI, this is called the SIS ID and can be modified by visiting the Settings for each respective sub-account.
- *parent_account_id: This identifier indicates that a sub-account should be nested beneath this parent account. If this field is blank then the sub-account will be nested beneath your root or main account. Note that even if all values are blank, the column must be included to differentiate the file from a group import.
- *name: This is the name for the sub-account.
- *status*: This is how you can create or remove a sub-account. Mark as active to add a sub-account or deleted to remove an existing sub-account.
A term provides a default set of start and end dates to any course assigned to that term. Term dates for courses can be manually managed at the course level without an import file. However, attaching a term_id to many different courses ensures all courses in that term begin/end at the same time. Uploaded term dates will also help you sort and organize courses when viewing data and reports in the Admin interface.
Download a sample terms.csv file with 10 terms.
- *term_id: This is a unique identifier for the term. The courses.csv will allow you to reference this term_id so your courses know when to start and when to conclude. This identifier must not change for the term, and must be globally unique across all terms. In the user interface, this is called the SIS ID.
- *name: This is the name of your term. Come up with a good naming convention that will help you easily reference your terms. There are many admin tools that allow you to search or query data by the term name.
- *status: This is how you can create or remove a term. Mark as active to add a term or deleted to remove an existing term.
- start_date: This is the date the term begins. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ (The T may be replaced with a space,as seen in the example screenshot.) For example August 26, 2013 at 5:00pm EST would be written 2013-08-26T17:00-5:00
- end_date: This is the date the term ends. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ (The T may be replaced with a space, as seen in the example screenshot.) By default, user access is cut off at midnight on your indicated end date, meaning the previous day is the last full day that users have access to the term. Best practice is to set your end date to the day after the term ends.
A course is an organized presentation about a particular subject. Sometimes a course may include a series of courses. Courses are placed within terms to create default start and end dates. However, if a course includes specific course dates, these dates will override the student access dates on the term, identified by the term_id (if included.) The value of attaching a term_id is that you will be able to sort and organize the courses when viewing data and reports, in the Admin interface. A term_id can be easily attached to many different courses that begin/end at the same time. If you do not link a course to a term then the course will be linked to the term called Default Term.
If your institution has enabled Blueprint Courses, you can use a courses.csv to add associated courses to a blueprint course. Please note that the blueprint course must be created and enabled as a blueprint course before associated courses can be added.
Download a sample courses.csv file with 10 courses; they reside within their respective sub-accounts in a specific term.
- *course_id: This is a unique identifier used to differentiate courses within Canvas. This identifier must not change for the course and must be globally unique across all courses. In the user interface, this is called the SIS ID.
- *short_name: This is a short name for the course. In the Canvas UI this is called the Course Code.
- *long_name: This is a long (full) name for the course. (This can be the same as the short name, but if both are available, it will provide a better user experience to provide both.)
- account_id: This is the unique account identifier (from the accounts.csv) which tells the course under which sub-account it will reside. If an account_id is not specified then the course will be attached to your main/root account.
- term_id: This is the unique term identifier (from the terms.csv) which tells the course when to begin and when to conclude. If associating a term_id with a course you do not need to enter a start_date or end_date.
- *status: This is how you can create, remove, or conclude a course. Mark as active to add a course or deleted to remove an existing course, or completed to conclude an existing course.
- start_date: This is the date the course begins. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ (The T may be replaced with a space.)
- end_date: This is the date the course ends. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ (The T may be replaced with a space). By default, user access is cut off at midnight on your indicated end date, meaning the previous day is the last full day that users have access to the course. Best practice is to set your end date to the day after the course ends.
- course_format: This is the format for the course. The format can be online, on_campus, or blended.
- blueprint_course_id: This is the SIS ID of the blueprint course to which you want to add an associated course.
A section subdivides students within a course. Multiple sections can also be cross-listed into one course, especially if all student sections are learning the same course material. Multiple sections can be placed in one course, but a section cannot contain multiple sections. Sections inherit the course dates as set by the term. However, if a section includes specific dates, these dates will override the student access dates for the course and the term start and/or end dates.
If you are trying to delete a course and the users are associated with sections, you'll need to include the section_id parameter in the CSV import as well as the section SIS IDs.
Download a sample sections.csv file with the following sections:
- 4 sections in the ACCT300 - Cost Accounting course
- 4 sections in the ACCT310 - Managerial Accounting course
- 2 sections in the BIO101 - Intro to Biology course
This file assumes that you may have multiple sections within one course. Many institutions import course sections as separate courses. This can be done by (1) creating a Canvas course for each section in your courses.csv, then (2) creating a single section in each of these courses. You may use essentially the same data for the course and section including the SIS ID which will be the same for both the course_id and section_id.
- *section_id: This is a unique identifier used to create sections within a course. This identifier must not change for the section, and must be globally unique. In the user interface, this is called the SIS ID.
- *course_id: This is the unique identifier of the course where the section will be added or deleted.
- *name: This is the name of the section. Sections are ordered alphabetically by name.
- *status: This is how you can create or remove a section within a course. Mark as active to create a section or deleted to remove an existing section.
- start_date: This is the date the section begins. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ (The T may be replaced with a space).
- end_date: This is the date the section ends. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ (The T may be replaced with a space). By default, user access is cut off at midnight on your indicated end date, meaning the previous day is the last full day that users have access to the section. Best practice is to set your end date to the day after the section ends.
An enrollment is a user who has been enrolled in a course under a specific role. An enrollments.csv allows you to assign roles to users and place them into the appropriate courses. When the enrollment status of any user is marked as completed they will be limited to read-only access for that course.
Download a sample enrollments.csv file with the following enrollments:
- 1 user as a teacher in the ACCT300 - Cost Accounting course
- 1 user as ta in the ACCT300 - Cost Accounting course
- 1 user as a designer in the ACCT300 - Cost Accounting course
- 3 users as students in section 1 of the ACCT300 - Cost Accounting course
- 3 users as students in section 2 of the ACCT300 - Cost Accounting course
- 1 user as an observer of a student in section 1 of the ACCT300 - Cost Accounting course
- *course_id: (Required if the section_id is missing) This is a unique identifier for the course where the user will be enrolled. If enrolling students into the course rather than a specific section, put the course_id in this field. Otherwise, leave it blank.
- root_account: This is the domain of the account to search for the user.
- *user_id: This is the unique identifier of the user that will be enrolled within the designated courses (added in users.csv).
- *role: This is the role that a user will will be assigned to a user for the designated course. You enroll a user to be any of the following roles: teacher, designer, ta, student, observer or a custom role that you define. Each role has a permission set that Admins can customize at the main/root account or sub-account level.
- role_id: (Required if role is missing) This is the unique identifier for the role in which the user will be added as part of an enrollment.
- *section_id: (Required if the course_id is missing) This is the unique identifier for the section in which the user will be enrolled. If enrolling students in a specific section of a course, put the section_id of the section here. Otherwise, leave this field blank. If no section_id is specified the default section for the course will be used. If a default section does not exist, one will be created automatically without an SIS ID.
- *status: This is how you enroll, conclude, deactivate (make inactive), or remove an enrollment in a course. Mark as active to enroll a user in a course, completed to conclude a user's enrollment in a course, inactive to deactivate the user in the course, and deleted to remove a user from a course. When in an 'inactive' state, a student will be listed in the course roster for instructors but will not be able to view or participate in the course until the enrollment is activated.
- associated_user_id: (Observer role only) This is the unique identifier of the user whose information (including grades) the observer will be able to view. The observer should be enrolled in the same course/section as the user you would like them to observe. This field will be ignored for any role other than observer.
- limit_section_privileges: This is how to designate that the enrollment will allow the user to only see and interact with users enrolled in the section given by course_section_id. This field defaults to false. Limiting students to interact by section only affects Collaborations, Chat, People, and Conversations. When enrolling instructors and TAs, section limitations allow those users to grade students in their same section(s). Discussion topics and Pages are not affected by section limitations and can be viewed by any student. These feature areas could be restricted by creating content in course groups.
A group can be used to provide collaborative opportunities for students, instructors, admins, or other users. A groups.csv allows you to create account-level groups. Groups uploaded via SIS can only be updated or deleted via SIS.
Download a sample groups.csv file with the following groups:
- Math Teachers
- *group_id: This is the unique identifier used to reference your group. It must not change for the group, and must be globally unique.
- account_id: This is the identifier that attaches the group to an account (added in accounts.csv). If none is specified, the group will be attached to the root account.
- *name: This is the name of the group.
- *status: This is the status of the group. Mark as available to set the group open for membership or deleted to delete the group.
Membership in a group allows users to collaborate on activities in Canvas. A groups_membership.csv allows you to bulk add or remove people to a group you have created via groups.csv.
Download a sample groups_membership.csv file with the following group memberships:
- 1 accepted user in the Admins group
- 1 accepted user in the Math Teachers group
- 1 deleted user in the Math Teachers group
- *group_id: This is the unique identifier used to reference your group (added in groups.csv).
- *user_id: This is the unique identifier of the user you want to add to the group.
- *status: This is the status of the users in the group. Mark as accepted to add a user to a group or deleted to remove a user from a group.
Cross-listing allows you to move sections into another course. A xlist.csv file allows you to cross-list sections into existing courses and create a section hierarchy.
Section ids are expected to exist already and already reference other course ids. If a section id is provided in this file, it will be moved from its existing course id to a new course id, such that if that new course is removed or the cross-listing is removed, the section will revert to its previous course id. If xlist_course_id does not reference an existing course, it will be created. If you want to provide more information about the cross-listed course, please do so in courses.csv.
Download a sample xlists.csv file with the following courses and sections:
- 4 active sections from the ACCT300 - Cost Accounting course cross-listed into the ACCT310 - Managerial Accounting course
- *xlist_course_id: This is the identifier of the new course (added in courses.csv).
- *section_id: This is the identifier of the section (added in sections.csv).
- *status: This is the status of the section. Mark as active to make the section active or deleted to remove the section.
The observer role can be used to enroll parents and link them to a student, allowing them to view their student's grades and course interactions. A user_observers.csv allows you to enroll and link observers to each of the designated student's enrollments.
Download a sample user_observers.csv file with the following enrollments:
- 2 active observers
- 1 deleted observer
- *observer_id: This is the unique identifier of the observer.
- *student_id: This is the unique identifier of the student.
- *status: This is the status of the observer. Mark as active to enroll the observer for each of the student's enrollments or deleted to remove all the observer's enrollments.
A SIS ID is a unique identifier for an object in Canvas. A change_sis_id.csv allows you to bulk change SIS IDs for existing accounts, terms, courses, sections, groups, or users.
Download a sample change_sis_id.csv file with the following SIS ID changes:
- 1 user SIS ID change
- 1 course SIS ID change
- 1 term SIS ID change
- *old_id: This is the current SIS ID of the object.
- *new_id: This is the desired SIS ID of the object. The new SIS ID must be currently unique to the object type and the root account.
- *type: This is the type of object. Type can be account, term, course, section, group, or user.
Admins manage settings for an entire account or subaccount. An admins.csv allows you to designate users in Canvas as account admins or other custom account or subaccount roles.
Download a sample admins.csv file with the following admins:
- 2 active account admins
- 1 deleted account admin
- 2 active custom account roles
- user_id: This is the unique ID of the user you would like to designate as an admin.
- account_id: This is the unique identifier of the account in which you would like the admin to reside. If this column is left blank, the user will reside in the root account. This column is always required, even if the value is blank.
- role_id: (required if role is missing) This is the ID of the role, either built-in or defined by the account.
- role: (required if role_id is missing) This is the name of the role, either Account Admin or a custom role defined by the account.
- status: This is the status of the admin. Mark as active to create an active admin or deleted to remove an admin.
- root_account: This is the domain of the account to search for the user.