Clever API Overview

❗️
Clever Complete Agreement Required
This feature is included with a Clever Complete subscription. Sign up here or email your Application Success Manager to learn more.

Use this page to understand how to access the Clever API, choose the right token type, and review Clever’s API change policy.

Overview

Use the Clever API to access district, school, roster, and user data based on your application’s scopes and integration type.

If you want to explore endpoints, review schema details, or test requests, start with Exploring the Clever API.

Clever API status

Check status.clever.com to view current system status, past incidents, and future updates.

Access tokens

Clever supports two API token types:

District-app tokens for district-authorized access
SSO bearer tokens for user-authorized access

Use the token type that matches the integration and data you need.

District-app tokens

A district-app token is created each time a district authorizes your application. This token stores the details of that authorization. A district-app token is a string such as 7f76343d50b9e956138169e8cbb4630bb887b18.

Use district-app tokens when you need district-managed access to data shared with your application.

❗️
Tier access matters
If you are not a Secure Sync customer, district-app bearer tokens can only access /districts/ and related endpoints. Access to other endpoints is only available with SSO bearer tokens.
Section data and Events can only be accessed with district-app bearer tokens that belong to Secure Sync customers.

To learn how to obtain district-app bearer tokens, see Onboarding and Syncing with Clever.

SSO bearer tokens

SSO bearer tokens are issued for individual users, such as students, teachers, district admins, and school admins. The data available to these tokens is scoped to the user who authorized the token and the data available around that user.

SSO bearer tokens are strings with an il prefix, such as il3jsfUI2131da2f.

Use SSO bearer tokens when your app needs user-level access during a Clever Single Sign-On flow.

SSO bearer tokens can access:

/me
/users/<user id>
/schools/<school id>
/districts/<district id>

🚧
Limited field access
Some fields documented in the schema for these objects are not available when you query them with SSO bearer tokens.

API change policy

Clever updates the API by adding features, releasing new versions, and deprecating older versions over time. Use this policy to understand what changes to expect and when.

Switching to a new API version

To call a new API version, update the version in your request URL. For example: https://api.clever.com/v3.0/district.

For upgrade guidance, see Migrating to API v3.0.

Releasing new versions

Clever releases major versions, such as v2.0, no more than once per year. Minor versions, such as v1.2, are released as needed.

A minor release adds new features or bug fixes while remaining backward compatible. A major release may include breaking changes or deprecations.

When a new version is officially released, new applications cannot use previous API versions.

Updating versions after release

Clever considers a new version code-complete at release, but may still ship bug fixes during the first three months after release. After that period, the version is frozen and no further updates are made.

Global changes

Some changes apply to all API versions. When that happens, Clever updates the developer documentation accordingly.

Deprecating existing versions

Clever marks an API version as deprecated in the documentation when new customers can no longer use it. Clever will continue to support deprecated versions.

Clever has not yet published a formal API sunsetting policy.