GuidesClever App DashboardAPI Postman CollectionClever AcademySupportStatus
Guides

API v3.x Upgrade Guide

Welcome! 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.

Migration Checklist

  • ☑️ Audit current usage of role-based endpoints
  • ☑️ Identify where Clever IDs are stored or referenced
  • ☑️ Migrate to storing the v3 User ID
  • ☑️ Update all user-related API calls to use /v3.1/users
  • ☑️ Update logic that filters or processes events
  • ☑️ Review your handling of multi-role users
  • ☑️ Test against demo districts with v3 data

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

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.

Steps to upgrade

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. Accounting 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 15 days ago