GuidesClever App DashboardAPI Postman CollectionClever AcademySupportStatus
Guides
Start typing to search…

API v3.x Upgrade Guide


Table of Contents

Overview
What's New in v3.x?
Summary of Breaking Changes
Testing the v3.x endpoints (recommended)
Steps to Upgrade

Overview

This guide will walk you through upgrading your application from Clever API v2.x to v3.x, equipping you with the key changes, best practices, and decision points to support a smooth upgrade.

🤔

Questions?

If you have specific questions about your current implementation or specific challenges, feel free to contact [email protected] and we'd be happy to work through those with you.

What's New in v3.x?

The most significant change in v3.x is user consolidation: all users (students, teachers, staff, admins) are now represented by a unified Multi-Role User object.

Key Benefits:

  • One user = one Clever ID
  • More accurate role tracking
  • Better support for users with multiple roles (e.g., teacher + staff)
  • New features
    • Clever LMS Connect (v3.1)
      • API v3.1 introduces the Gradebook Sync API, which enables your app to support connections between your app, Clever, and the biggest LMS providers on the market. Learn more information here: Clever LMS Connect - Overview
    • Enhanced user demographic data (v3.1)
      • We've included additional demographic data points, such as student.section_504_status and student.disability.disability_status.
    • Attendance Data Support (v3.1)
      • Coming soon!
    • Content Mapping (v3.0+)
      • API v3.0 introduced the Content Mapping API, which allows districts to map specific resources to a course in Clever.
      • This associates the resource with not only the course, but also related sections and users, which can be used to inform downstream user routing, or content access.
      • See this page for more information: Resources

For more exhaustive changes in API v3.x, please refer to our existing doc pages on v3.0 and v3.1:

Summary of Breaking Changes

Areav2.xv3.x
User EndpointsRole-specific endpoints (e.g., /teachers, /students, etc.)Consolidated role endpoints; filter by role (e.g., /users?role=teacher, /users?role=student, etc.)
User IDsRole-specificRole-agnostic
Events APIFilter by record_type= to obtain specific user eventsAll user events returned; filter in application by role
Related EndpointsUses legacy role-based IDsUses Multi-Role User ID

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

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:

  1. Iterate through the role array on the v3.x user object
  2. Looking at each node, match legacy_id value of each role against your existing accounts.
  3. 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.

Testing the v3.x endpoints (recommended)

Prior to beginning your upgrade work, we recommend testing the v3.x endpoints to familiarize yourself with the changes and responses in API v3.x. This will be particularly useful for understanding how user records are displayed, along with their role(s).

The best way to do this is by using the Clever API Developer Collection in Postman. Please see this page for more information on accessing the collection and interacting with the Clever API.

👍

Ready to Upgrade? Continue to the steps below.

Steps to upgrade

Migration Checklist

1. Audit current usage of role-based endpoints

To begin, we recommend reviewing your integration for any endpoints that currently rely on role-based querying to obtain the relevant user data. For example, this includes, but is not limited to:

  • /v2.0/students
  • /v2.0/teachers/{id}
  • /v2.1/teachers/{id}/sections
  • /v2.1/school_admins/{id}

Any endpoint in your existing integration that currently makes calls to the above or similar endpoints for user-related data will need to be updated to use their v3.x equivalent. You should take note of what endpoints your integration currently uses, and be prepared to update those once you've completed the next step - Migrating to the v3.x User ID.

2. Migrate to the v3.x User ID

In v3.x, every user has a new universal Clever User ID. This ID is the same in v3.0 and v3.1. You must update your application's database to associate users with their new ID, as your application will need to refer to this new ID for all calls that require a specified user ID, for example, /v3.1/users/{id}.

💡

Did you know?

Students are the only user type whose legacy_id and id values on their user record will be the same, since they cannot be assigned multiple roles.

Migration Strategy:

  • Fetch all users via /v3.1/users
  • Match with existing records (email, SIS ID, etc.)
  • Store the new user ID in your database
  • Use v3 user ID in all related endpoint calls
  • Request API v3.x Migration CSVs via the App Dashboard
    • This tool can be found under Settings > District Setup:

3. Update your User Endpoints

Example use case: Querying teacher accounts in bulk

GET /v2.1/teachers
Authorization: Bearer {district_app_token}

GET /v3.1/users?role=teacher
Authorization: Bearer {district_app_token}

User Endpoint Changes

v2.xv3.x
/students/users?role=student
/teachers/users?role=teacher
/school_admins/users?role=staff
/district_admins/users?role=district_admin
/students/{id}/users/{id}
/teachers/{id}/users/{id}
/school_admins/{id}/users/{id}
/district_admins/{id}/users/{id}

Related Data Endpoint Changes

Any endpoint that previously used a role-specific ID to return associated data must now use the v3 user ID.

v.2xv3.x
/teachers/{id}/mystudents/users/{id}/mystudents
/students/{id}/teachers/users/{id}/myteachers
/students/{id}/mycontacts/users/{id}/mycontacts
/teachers/{id}/sections/users/{id}/sections
/students/{id}/sections/users/{id}/sections
/students/{id}/schools/users/{id}/schools
/teachers/{id}/schools/users/{id}/schools
/school_admins/{id}/schools/users/{id}/schools
(new)/users/{id}/resources

It should be noted here that non-teaching school staff, such as guidance counselors, principals/vice principals, and school nurses are no longer called school admins in Clever. In v3.x and on, Clever will refer to these users as staff.

4. Adjust Event Handling (if applicable)

The Events API is an optional implementation to sync only data changes via Created, Updated, and Deleted events generated when a connected district makes changes that affect the data shared with your application. If your application uses the Events API on v2.x, you will need to update how your application handles user events for API v3.x.

The Events API no longer supports filtering by user type. For example:

GET /v2.0/events?record_type=student

GET /v3.1/events?record_type=users
👍

Best Practice: You’ll need to filter events by user role on your end using the user object returned in each event.

Please note, the v3.x Events API still adheres to the event ordering used on API v2.x. Your integration should continue to process events in the order they are received, not by event type.

For more information on the Events API, please refer to the Updating Data with Events page.

5. Account for Identity API Changes (SSO)

The type field on /me will now return "user" for any user records instead of a specific role type.

Example /me response:

{
    "type": "user",
    "data": {
        "id": "63850203bfb8460546071e63",
        "district": "6385008f69df036e83e984a3",
        "type": "user", // Now always returns "user"
        "authorized_by": "district"
    },
    "links": [
        {
            "rel": "self",
            "uri": "/me"
        },
        {
            "rel": "canonical",
            "uri": "/v3.1/users/63850203bfb8460546071e63"
        },
        {
            "rel": "district",
            "uri": "/v3.1/districts/6385008f69df036e83e984a3"
        }
    ]
}
🚧

Important: Do not rely on the type field to provide role information anymore — use the roles array on the user record to better understand the user's context.

6. Plan for Multi-Role Users

As district needs have evolved rapidly over time, many users now have multiple roles (e.g., both a teacher and staff). Your app should be able to gracefully handle this use case.

📘

For more detailed information on handling multi-role users, please refer to the Multi-Role Users in Clever doc.

Option 1: Consolidate roles into one app account

  • One account per user, regardless of role

Option 2: Role-specific accounts

  • Treat each role as a separate account
  • Allow the user to easily switch between the two account roles in your app via UI

Permissions and Access

You'll also need to consider how these multi-role users will be granted access to specific functions of your application, depending on your use case. For example, you could assign permissions based on highest role available from Clever, or allow District Admins to manually assign elevated permissions in your app.

7. Testing with sandbox data

Once you've completed the above changes, we recommend using your existing sandbox district and Clever dev application to test your app's capabilities using API v3.x. If you're using the Events API, we recommend connecting with the #DEMO Certification ISD - Events sandbox district, which automatically rotates through a 3-day data set. If your dev app is not already connected, please contact [email protected] to have your dev app connected to #DEMO Certification ISD - Events.

Updated 5 days ago

What’s Next