Overview and Best Practices
API Version 2.0, published 11/03/2017
Clever guarantees required fields are always present in the given resource. Clever guarantees fields with validation will only contain the possible values or formats listed. All other data is shown as it exists in the source system.
Data availability is subject to the decision of schools or districts to share their data.
Resource availability depends on your application's scopes.
Our API Explorer (below!) allows you to test out endpoints. In addition, the /{record type}/{id} endpoints contain the detailed list of fields for each record type. Information that is guaranteed, as well as data that is validated or normalized by Clever, will be marked on that endpoint.
Testing the API Explorer
Use your API token here if you have one, or you can use 'TEST_TOKEN' to explore the API.
For relationships between records and our full schema, check out Clever's Data Model.
Queries on the Clever API can return large numbers of results. To improve performance and make the data more consumable, the Clever API supports paginating large responses.
To iterate through results, you should follow the rel:next
link contained with every set of results. For example, querying the /students
endpoint with a district bearer token you might see the following:
"links": [
{
"rel": "next",
"uri": "/v1.1/students?starting_after=530e5961049e75a9262cffe4"
}
]
The link uses the starting_after parameter to jump to the next page of results. This form of pagination is called range-based pagination. Elements are returned sorted with ascending IDs (based on create time).
Using relative links for pagination
If there are more results to consume, the response's links object will have a rel link called next, that lets you query the next page of results. Similarly, there may be a prev link for the previous page of results.
Example links object for request GET /v1.2/districts?starting_after=53ced71e65a64d5918157c04:
"links": [
{
"rel": "self",
"uri": "/v1.1/districts?starting_after=53ced71e65a64d5918157c04"
},
{
"rel": "next",
"uri": "/v1.1/districts?starting_after=56fad73b82c6fd818c6b48cc"
},
{
"rel": "prev",
"uri": "/v1.1/districts?ending_before=53ced71e65a64d5918157c04"
}
]
starting_after queries may have prev links even when there are no previous results. Following such links will return an empty array of data. Similarly, ending_before queries may have next links even when there are no more results, and following those links will return an empty array.
Rather than serving every result at once, by default the Clever API limits the number of entries in responses to 100 per page. You can change the number of results returned by setting the limit parameter. For instance, GET /v1.1/students?limit=30
returns at most 30 students
The maximum limit is 10000 records per page.
API Responses and Error Handling
200
Success
Process the response.
400
Bad request
Check your API token and request body. Do not retry request. The troubleshooting pages for each API also have tips for what to look for!
401
Invalid auth
Check your API token and request body. Do not retry request. The troubleshooting pages for each API also have tips for what to look for!
404
Resource not available
Check your API token and request URL - you may be using the wrong token or the resource may have been unshared with your application or deleted.
413
Request entity too large
Your limit
parameter may be over 10000; reduce accordingly.
429
Rate limit exceeded
Try again after rate limit period expires.
500
, 502
, 503
Clever API failure
Wait and retry request. If you see these regularly, reach out to tech-support@clever.com.
501
Not implemented
Your client is attempting an unsupported request. Try an alternative request. Do not retry request.
Requests to Clever are rate-limited. Requests are limited to 1200 requests per minute per Bearer Token (instant login or district). These limits are not averages; rather, the allowed count of requests resets every minute.
Rate-limited requests contain these HTTP response headers:
- X-RateLimit-Reset: Unix timestamp when the rate limit counter will be reset.
- X-RateLimit-Limit: The total number of requests allowed in a time period.
- X-RateLimit-Remaining: Number of requests that can be made until the reset time.
- X-RateLimit-Bucket: Name of the rate-limit bucket for this request
Request:
HOST api.clever.com
GET /v1.2/students/123
AUTHORIZATION Bearer ABCD
Response headers:
Status: 200 OK
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1199
X-RateLimit-Reset: 1394506274
X-RateLimit-Bucket: abc123
In case the client hits a rate limit, an empty response with a 429 Too Many Requests
status code is returned.
Request:
HOST api.clever.com
GET /v1.2/students/123
AUTHORIZATION Bearer ABC
Response headers:
Status: 429 Too Many Requests
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1394506274
X-RateLimit-Bucket: abc123
When a request against the Clever API fails, use a retry strategy with exponential backoff (i.e. wait 1 second after first error, then 2, then 4, etc.). If you are unable to receive a successful response after five retries, you may want to cease the sync and resume at a later time.
See example exponential backoff implementations in PHP and C#.
It's unlikely that our APIs are down, but parts of the API naturally have outages here and there. Check status.clever.com to see how Clever is doing or review past outages. You can even subscribe to notifications so you'll always know what's going on.