Using the Canvas API to Automate Observer Account Creation
By Liam Beveridge
The process of creating and pairing an observer account can be confusing for parents and guardians that are new to Canvas, especially when they already have a lot on their plate with the start of school. Furthermore, helping parents and guardians create observer accounts can become a significant source of support tickets at the beginning of the school year. By automating the observer account creation process, we can save families and the support team effort while ensuring that every student ends up with an observer who can monitor their success moving forward. In this article, we will walk through how the Canvas API can be utilized to automate creating and pairing observer accounts. We are assuming familiarity with programming and working with APIs here since this is a fairly technical process, but we will also link some helpful resources on the technologies we’ve used to implement this near the end of the article.
Our goal for this automation is to take a list of student IDs and email addresses of parents or guardians so that we can create an observer account for each parent/guardian and pair it with the appropriate student or students. We will also need the first and last name of each parent/guardian to create the observer accounts with. To allow for students enrolling throughout the year, we want this automation to be able to be run regularly, and not just as a batch process once at the beginning of the year. Of course, this only works if the data in your SIS is up-to-date and accurately contains parent contact information. Here is a breakdown of each call we need to make as we iterate through the list of students and observers:
First, we need to determine if the current student’s observer already has an account in Canvas, and whether or not it needs to be paired. We will make the following API calls to do this:
Get the student’s Canvas ID:
Before we create an observer account, we should make sure that the current student has an account in Canvas, and generate a pairing code. We can use a student’s SIS ID or email to search for their Canvas ID using the API.
We can use the users API endpoint to make a get request to search for the student: /api/v1/accounts/self/users?search_term=<SIS ID or email>&per_page=100
Once the API call returns, if more than one user is returned we can iterate through the returned users for the user that exactly matches the search term. This is necessary because if you search for a user with the ID 100, Canvas will also return users with ID’s 1001, 1002, etc.
Look up the ID of the observer in Canvas using their email address to see if they already exist in Canvas.
Once again, we can use the users API endpoint to make a get request to search for the observer’s Canvas ID: /api/v1/accounts/self/users?search_term=<email>&per_page=100
If the observer exists, check if they are already paired with the student:
Now we can use the observer’s Canvas ID to make a get request to the user observees API to check if they are already paired with the current student: /api/v1/users/%s/observees"%(observer_id)
After iterating through the results to check for the student’s ID in the returned observees, we can either skip to the next student, or proceed.
Now that we have the user’s ID, and know that they need to be paired, we can try to generate a pairing code.
Attempt to generate pairing code:
A post request to the users API observer_pairing_codes endpoint with the student’s ID can be used to generate a pairing code: /api/v1/users/<student id>/observer_pairing_codes%(student_id)
If a student is not currently enrolled in any classes, the call to generate a pairing code will fail with a 401 status. Since we can’t pair this student, we can skip to the next student.
If the pairing code is generated successfully, and the observer doesn’t already exist, we now need to create a new observer account:
Create a new observer account:
We can pass the observer’s email address and name to the users API endpoint to a post request to create their account: /api/v1/accounts/1/users?user[name]=<observer full name>&pseudonym[unique_id]=<email address>&pseudonym[force_self_registration]=true
When the account is created, the observer will receive confirmation at their email address with login instructions.
Since we have created the observer account, or verified that it has already been created, we can use the generated pairing code to pair it:
Pairing the observer account:
This post request can be used to pair the accounts: api/v1/users/<observer canvas ID>/observees?observee[unique_id]=<student canvas ID>&pairing_code=<pairing code>
We hope the above outline serves as a helpful guide for how to implement an automation to create and pair observer accounts. If using the process above, the automation can be run on a regular schedule to create observer accounts for any newly enrolled families, and pair new students to existing observer accounts. We implemented our observer creation automation using Python, using the Async IO library. Using asynchronous requests allows us to run our API calls for multiple students simultaneously, significantly reducing the amount of time it takes for the automation to complete. Real Python has a great guide to Async IO. The Real Python guide to interacting with REST API’s through Python is another helpful resource for anyone who hasn’t worked with API’s previously. Even if implementing this automation is out of your current scope, we recommend downloading an API platform like Postman, and spending some time getting familiar with the Canvas API. Canvas’s API documentation, including how to authenticate, is available here. The Canvas API gives admins access to many settings and features that aren’t available through Canvas’s user interface, and you may discover other helpful automations you could implement.