How do I format CSV text files for uploading SIS data into a Canvas account?

How do I merge users in an account?

Canvas allows you to import CSV files to manually bulk create users, accounts, terms, courses, sections, enrollments, and logins 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 the SIS relationship diagram.

Sample Files

Each step in this lesson provides details about the CSV files and descriptions of each required and optional field. Each step also includes a link to download a sample CSV file. Sample files contain all required fields and may also contain optional fields. Additionally, you can download a zipped package of all sample files. If CSV links do not download, try opening the link in a new tab.

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.

Sticky Fields

By default, certain changes made in the user interface are not overwritten by future SIS imports and are specified as being sticky. All sticky fields are identified in this document. You can override these fields by setting override_sis_stickiness in the API or checking the Override UI changes checkbox in the SIS Import page.

API Documentation

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

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.

Required Field* | Sticky Field^

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.
authentication_provider_id: This is the authentication provider the login is associated with. Logins associated with a specific provider can only be used with that provider. Legacy providers (LDAP, CAS, SAML) will search for logins associated with them, or unassociated logins. New providers will only search for logins explicitly associated with them. This can be the integer ID of the provider, or the type of the provider (in which case, it will find the first matching provider).
first_name^: This is the given (first) name of the user. If present, used to construct full_name and/or sortable_name.
last_name^: This is the surname (last) name of the user. If present, used to construct full_name and/or sortable_name.
full_name^: This is both the given and surname of the user. Omit first_name and last_name if this is provided.
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.
pronouns: If personal pronouns are enabled, these are the personal pronouns that display after a user's name in Canvas. The pronouns field accepts all pronouns, even if they were not created in the Account Settings page.
declared_user_type: This declared user type can be either administrative, observer, staff, student, student_other, or teacher. Can pass "<delete>" to remove the declared user type from the user.
canvas_password_notification: This defaults to false. When true, user is notified for password setup if the authentication_provider_id is Canvas. If your institution does not have a Canvas SIS integration, this field is required to notify new users of their created accounts.
home_account: Setting the home_account as true will create a new user in the target account for the SIS import and merge in another existing user from another account within the consortium with a matching integration_id. Will be ignored unless the target account is associated with an auto-merge consortium.
status*^: This is where you can add or remove a user from Canvas. Mark as active to add a user, suspended to suspend 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.

accounts.csv

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)

Required Field* | Sticky Field^

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.
integration_id: This is a secondary unique identifier useful for more complex SIS integrations. This identifier must not change for the account, and must be globally unique.

terms.csv

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.

Required Field* | Sticky Field^

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.
integration_id: This is a secondary unique identifier useful for more complex SIS integrations. This identifier must not change for the term, and must be globally unique.
date_override_enrollment_type: This allows you to set or remove start and end dates for a specific enrollment type within an existing term. When set, all columns except term_id, status, start_date, and end_date to be ignored for the row. If status is set to active, the term dates will apply only to enrollments of the given type. If status is set to deleted, the currently set dates will be removed for the given enrollment type. Enrollment type can be set to StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment.

courses.csv

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.

Required Field* | Sticky Field^

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 also called the Course Code or Reference 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 SIS ID account identifier (from the accounts.csv) which tells the course under which sub-account it will reside. If an account_id is not specified for a new course, then the course will be attached to your main/root account. The SIS ID can be found in the subaccount's Settings.
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 the status of the course, also known as the workflow_state. This field allows you to create, remove, conclude, or publish a course. Mark as active to add a course, deleted to remove an existing course, completed to conclude an existing course, or published to publish an existing course.
integration_id: This is a secondary unique identifier useful for more complex SIS integrations. This identifier must not change for the course, and must be globally unique.
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 course ID of the blueprint course to which you want to add an associated course. To remove the Blueprint Course link you can pass 'dissociate' in place of the ID. In the user interface, this is the SIS ID of the blueprint course.
homeroom_course: This is used to designate homeroom courses for Canvas for Elementary accounts. Requires the Canvas for Elementary setting to be enabled.

sections.csv

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.

Required Field* | Sticky Field^

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 (added in courses.csv).
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.
integration_id: This is a secondary unique identifier useful for more complex SIS integrations. This identifier must not change for the section, and must be globally unique.
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.

enrollments.csv

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.

Note: SIS enrollment CSV files that include start_date and end_date values override term dates, course dates, and section dates.

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

Required Field* | Sticky Field^

course_id*: (Required if the section_id is missing) This is a unique identifier for the course where the user will be enrolled (added in courses.csv). 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.
start_date^: This is the enrollment start date. For start_date to take effect, the end_date also needs to be populated. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ.
end_date^: This is the enrollment end date. For end_date to take effect, the start_date also needs to be populated. The format should be in ISO 8601: YYYY-MM-DDTHH:MM:SSZ.
user_id*: This is the unique identifier of the user that will be enrolled within the designated courses (added in users.csv). If the user_integration_id is present, this field will be ignored.
user_integration_id*: (Required if the user_id is missing) This is the secondary unique identifier of the user (added in users.csv as the integration_id).
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 (added in sections.csv). 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.
notify: This is how you choose to send a notification to the enrolled user(s) when they are enrolled in a course.

Note: The root_account field is recommended when identifying users in a trusted account.

group_categories.csv

Group categories allows you to organize groups in Canvas. A group_categories.csv allows you to create group categories at the account or course level. In the user interface, group categories are called group sets.

Download a sample group_categories.csv file with the following group categories:

Admin Groups
Designer Groups
History Project Groups

Required Field* | Sticky Field^

group_category_id: This is the identifier used to reference the group category. The identifier must not change for the group category, and must be globally unique.
account_id: This is the identifier that attaches the group category to an account (added in accounts.csv). If no account or course is specified, the group will be attached to the root account.
course_id: This is the identifier that attaches the group category to a course (added in courses.csv). If no course or account is specified the group will be attached to the root account.
category_name*^: This is the name of the group category.
status*: This is the status of the group category. Mark as active to create the group category or deleted to delete the group category.

groups.csv

A group can be used to provide collaborative opportunities for students, instructors, admins, or other users. A groups.csv allows you to create course-level and 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:

Admins
Math Teachers
Designers

Required Field* | Sticky Field^

group_id*: This is the unique identifier used to reference your group. It must not change for the group, and must be globally unique.
group_category_id: This is the identifier of the group category (added in group_categories.csv) into which you are adding a group. If no group category is specified, the group will be placed in the default group category for the defined account or course. If no account or course is specified, the group will be placed in the default group category for the root account.
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.
course_id: This is the identifier that attaches the group to a course (added in courses.csv). If no course or account 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.

groups_membership.csv

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

Required Field*

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 (added in users.csv).
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.

xlists.csv

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

Required Field*

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.

user_observers.csv

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

Required Field*

observer_id*: This is the unique identifier of the observer (added as the user_id in users.csv).
student_id*: This is the unique identifier of the student (added as the user_id in users.csv).
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.

logins.csv

The logins.csv allows you to create or update login credentials for users. Logins can only be added to existing users. Logins can be removed using the users.csv.

Download a sample logins.csv file with three user logins.

Required Field* | Sticky Field^

user_id*: This is the unique identifier of the user (referenced in enrollments.csv). This value must not change for the user and must be unique across all users. Called the SIS ID in the Canvas user interface.
integration_id: This is a secondary unique identifier useful for complex SIS integrations. This value must not change for the user and must be unique across all users. This field should be left blank when merging users with matching integration IDs.
login_id*: This is the name that the user would use to log in to Canvas. For configured authentication services, such as LDAP, this will be the username from the remote system.
password: This is the password that the user will use to log in to Canvas. This field should not be filled for accounts configured to LDAP or SSO.
ssha_password: This is a password generated with a pre-hashed SSHA generation scheme.
authentication_provider_id: This is the authentication provider that the login is associated with.
existing_user_id^: This is the user's SIS ID, as found in the users.csv.
existing_integration_id^: This is the user's integration ID, as found in the users.csv.
existing_canvas_user_id^: This is the user's Canvas ID.
root_account: This is the domain account for the user.
email: This is the user's email address.

Notes:

One of existing_user_id, existing_integration_id, or existing_canvas_user_id is required for a successful import of logins.csv.
The root_account field is required when identifying users in a trusted account (e.g., when cross-listing users across accounts within a trusted account).

admins.csv

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

Required Field*

user_id*: This is the unique ID of the user you would like to designate as an admin (added in users.csv).
account_id*: This is the unique identifier of the account in which you would like the admin to reside (added in accounts.csv). 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 the default ID or a custom ID defined by the account.
role*: (required if role_id is missing) This is the name of the role, either the default Account Admin role or a custom role defined by the account. If you are adding an account admin, format the field to read 'AccountAdmin'. If you are adding a custom role, format the field exactly as it appears in the Canvas UI.
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.

change_sis_id.csv

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

Required Field*

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.

You're signed out

How do I format CSV text files for uploading SIS data into a Canvas account?