Clever Developer Docs

Clever API Overview

Here, we'll discuss how to access data in our API as well as our API change policy. Check out
our reference docs for details on our schema, examples of error handling, and to test API calls.

Clever API Status

Check status.clever.com to view Clever's current system status as well as any past issues. Subscribe so that you can be notified of any issues in the future.

Access Tokens

There are two methods of accessing our API – district-app bearer tokens and Instant Login bearer tokens.

District-App Tokens

Every time a district authorizes your application, a token is created that stores the details of this authorization. A token is a string of characters: 7f76343d50b9e956138169e8cbb4630bb887b18

If you aren't a Secure Sync customer, district-app tokens can only access /districts/ and its related endpoints. You can access information on other endpoints only with Instant Login bearer tokens.

Section data and Events can only be accessed with district-app bearer tokens belonging to Secure Sync customers.

See our article on onboarding districts for information on obtaining district-app tokens.

Instant Login Bearer Tokens

Instant Login bearer tokens relate to individual students, teachers, district admins and school admins. The data available to these tokens are generally scoped to data "around" the owner of the token. For example, a student token can retrieve information about the student represented by the token, a teacher token can retrieve information about the teacher represented by the token, etc. Instant Login tokens are strings with an il prefix: il3jsfUI2131da2f

Instant Login tokens may only access:

  • /me
  • /<user type>s/<user id> - (not a typo! user_type is singular, but endpoints use the plural form)
    • For a student's IL token, you could access /students/<user id>
  • /schools/<school id>
  • /districts/<district id>

Please note that some fields referenced in the schema for these objects are inaccessible via these tokens.

API Change Policy

Clever is committed to providing the best experience for developers building on our platform. In order to make it easier and faster to build on Clever, we constantly improve by adding new features and deprecating ones that might get in the way. Here's what to expect from Clever when we make changes to our API.

Changes to v1.1 & API Versioning

As we've released API v1.2, we are no longer adding features to v1.1. Any future changes will be built into upcoming versions instead.

We sometimes need to make changes to all API versions - if we do, we will use the policy below.

When Additions are Made

Below is our policy for making additions to our API. Examples of these include:

  • adding additional fields to response JSON (e.g. “eye_color” field added to student resource)
  • adding new enumerated values in a field (e.g. “eye_color” field can now have value “hazel”)
  • adding a new API resource
  • adding a rel link

Notice Given: Announced via monthly Application Newsletter - subscribe by sending an e-mail request to newsletters@clever.com.
Developer Advice: In order to stay resilient to any additions to the API, be sure to parse JSON in a non-strict fashion. For example, make sure your JSON parser does not fail on unknown properties when new properties are added to objects.

When Deprecations Occur

Below is our policy for making deprecations to our API. Examples of these include:

  • removing an enumerated value (e.g. “eye color” will no longer have the value “hazel”)
  • removing a field (e.g. “eye color” is no longer part of the student resource)

Notice given: Six months notice via monthly Application Newsletter, with periodic reminders
Developer Advice: Clever will do its best to avoid deprecations, but when they are necessary, we’re more than happy to help you make necessary transitions.