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.
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.
There are two methods of accessing our API – district-app bearer tokens and Instant Login bearer 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:
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 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
Instant Login tokens may only access:
/<user type>s/<user id>- (not a typo!
user_typeis singular, but endpoints use the plural form)
- For a student's IL token, you could access
Please note that some fields referenced in the schema for these objects are inaccessible via these tokens.
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.
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 [email protected]
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.
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.
Updated 2 years ago