Migrating to API 3.0
Deprecation Notice
On July 31, 2025, Clever will be deprecating the API v2 contacts endpoint. You will need to update your Clever integration to use the contacts endpoint in API v3. There is no planned deprecation for other endpoints in API v2, so your integration can continue using any other API v2 endpoints as desired.
We estimate the migration will take 1-4 weeks depending on your current integration setup and engineering resources.
The API v2 contacts endpoint assigns a single relationship to each contact, which can result in inaccurate or misleading data when a contact is associated with multiple students.
API v3 resolves this issue by allowing contacts to have distinct relationships for each associated student, ensuring accurate and reliable data.If you have questions, please reach out to [email protected].
Multi-role Users Overview
Pre API v3.0 Behavior
In API v2.1 and earlier, each user type (students, teachers, school admins, district admins, and student contacts) was treated as a separate object. This required individual API calls and lacked a unified way to identify users with multiple roles. For example, a teacher with both teacher and staff accounts needed separate credentials for each role, creating confusion for end users and challenges for applications managing these accounts.
API v3.0 and Beyond
With the release of API v3.0, all user types were consolidated into a single user object. This change simplifies handling for education professionals with multiple roles, reduces API call complexity, and eliminates issues caused by duplicate accounts. By streamlining user management, Clever enables applications to better support users while ensuring accurate data ingestion and fewer redundancies.
If your application supports syncing teachers, staff (school admins), or district admins, it's likely multi-role users currently have separate accounts within your application and therefore receive a set of user permissions based on their role.
v3.0 Data Browser View (Secure Sync Only)
Did you know that you can toggle your view of the Data Browser between v2 and v3? Look for the toggle in the top right corner of your Data Browser page.
Managing Permissions, Access, and User Experience
Permissions and Access
Now that one user record may have two or all three of these roles, you'll need to consider how you apply access permissions in your product. If, for example, a teacher should have edit permissions for their classrooms and an administrator should have view-all access to their associated school sites, then your application will need to govern their access by determining which classrooms a user directly teaches (/users/{id}/sections) and which schools they administer (/users/{id}/schools).
If permissions are more broadly defined, you could assign a maximum or minimum set of permissions based on which roles are present. For example, if a staff member should always have a super-set of permissions, then a teacher who is also a staff member (or becomes a staff member) should be assigned staff-level permissions.
User Experience
If you have completely different user experiences for teachers, staff, and district admins in your application, consider providing an easy way for multi-role users to toggle between experiences in your UI.
Leveraging new staff roles
The user type previously called school admins is now staff to better represent a broader range of district and school roles beyond traditional admins or teachers. This change helps districts more accurately align user roles in Clever with specific job functions (counselors, custodians, librarians), improving flexibility and role clarity.
Within the staff response for users with a staff role is now another roles designation, indicating whether the user has access as a PortalOnly user or whether the district has designated them a SchoolTechLead in Clever. School Tech Leads support classrooms in their use of technology and receive a special set of permissions and features in Clever. PortalOnly staff are given the standard portal experience.
In your application, you might consider granting SchoolTechLead users additional access or permissions not afforded to PortalOnly staff, based on how those who commonly receive this designation--ed tech coaches, technology specialists--currently support classroom learning with your application.
The title field is an optional field that districts can include in their SIS sync with Clever to specify the user's specific function within the district. For more information on the staff data model, please see this page: Staff User Type Below, we've included an example staff user response.
{
"data": {
"created": "2022-11-28T18:46:36.799Z",
"district": "6385008f69df036e83e984a3",
"email": "[email protected]",
"last_modified": "2022-11-28T18:46:36.799Z",
"name": {
"first": "Lucy",
"last": "Freemont"
},
"id": "63850203bfb8460546071eef", //Clever API v3.x ID (multi-role user ID)
"roles": {
"staff": {
"credentials": {
"district_username": "[email protected]"
},
"department": "",
"roles": [
"PortalOnly"
],
"schools": [
"63850203bfb8460546071e5f"
],
"staff_id": "12342",
"title": "Principal",
"legacy_id": "63850203bfb8460546071ee2" //Clever API v2.x ID
}
}
},
Migrating users
We now have a migration tool that can help you match user legacy IDs to their new v3.x user IDs! Find out more here.
For some applications, data need not be stored or revived every new school year for returning users. In these cases, the simplest migration path is to pick a date and time over the summer to switch over to API 3.0, when no users from the prior year are expected to still be using your program. When districts return for Back to School, you'll begin syncing with all new data.
For most partners, we'll want to ensure users are migrated seamlessly to version API 3.0.
Students
All student Clever IDs from all prior API versions will remain the same in API 3.x.
Teachers, Staff, District Admins
In API 3.0, teacher, staff, and district admin roles contain a legacy_id field within each 'role' object, containing the Clever ID from previous API versions. The Clever ID at the /users level should supersede all IDs in your database.
Contacts
Upgrading from v2.x Contacts to v3.x Contacts?
With v3.x of the Clever API, significant updates were made in how Clever handles student relationships with contacts (guardians). We recommend reviewing these pages for more information:
Multi-role users
For users that now have multiple roles, you'll want to merge records that had previously existed as separate users in prior API versions to the new user Clever ID.
If your application has separate accounts for users that are both teacher and staff, we recommend associating each account with their id (v3.x user ID) value as opposed to continuing to rely on the legacy_id field as a primary identifier.
Here is an example workflow for how you can migrate users to their new identifiers:
- Iterate through the
rolearray on the v3.x user object - Looking at each node, match
legacy_idvalue of each role against your existing accounts. - If the user matches an account in your system, associate it with the provided
id(3.x user ID) value.
Alternatively, please be sure to check out our v3.0 Migration Tool!
If you must create separate accounts for each user type, developers can add complete matching by role by adding the ?role parameter to the user endpoint, and using the respective role fields. Note: separate accounts will have one Clever ID for updates moving forward.
How are Contacts handled in v3.x?
Contacts were included in the v3.0 user object consolidation and can be retrieved by making a GET request to https://api.clever.com/v3.0/users?role=contact.
However, a contact cannot be a multi-role user. This differs from the other user types in Clever, such as teachers, staff, and district admins. As an example, if the same person has a teacher and a contact role at a district, they will have two separate accounts: one for their teacher role, and one for their contact role. The will also have different Clever IDs.
Updated 18 days ago