API Version 1.1, published 8/12/2012

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.

Schema

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.

For relationships between records, check out Clever's Data Model.

Field formats

In our documentation on each endpoint, we'll refer to a few field formats. Here's what they mean and important information about each one!

ObjectID

All Clever IDs take the ObjectID format. We guarantee that ObjectIDs are globally unique across districts and user types.

String

Clever's strings have no maximum length - if you have to set maximum character lengths for fields, we recommend setting the max to 255 characters for safety.

Date

When a district provides Clever with term start and end dates, we validate that the field is some kind of expression of time but do not yet normalize that to a consistent representation.

Because of this, you may encounter strings like:

  • "2015-08-25"
  • "2015-08-25T00:00:00.000Z"
  • "2015-08-25 00:00:00.000000"

For best results, your application should consider all of these strings as equivalent to "2015-08-25"

Boolean

Booleans have a value of either:

  • Y
  • N

Link

Relative links are one way to discover and navigate to related data.

Let's examine the tail end of the JSON response to /me while using a student instant login token. Here's an example links node:

"links":
  [
    { "rel":"self","uri":"/me" },
    { "rel":"canonical","uri":"/v1.1/students/4fee004cca2e43cf2700028b" },
    { "rel":"district","uri":"/v1.1/districts/4feecb637de9810111e000002" }
  ]

Each relative link is structured:

rel - a string containing a keyword describing why you might be interested in the uri part
uri - a string containing the path component of a Clever API request

The rel keyword you're most interested in while handling this step is canonical. This is a fancy way of saying that the primary way to retrieve information about the object described in your API request is by requesting the path in the uri key.

To use that uri, you would attach the path component to https://api.clever.com. In the above canonical example, that would be https://api.clever.com/v1.1/students/4fee004cca2e43cf2700028b. This path will be accessible using the same instant login token or the appropriate district bearer token.

We strongly recommend following relative links to access related pieces of data. Constructing URLs by hand can be prone to errors and by following relative links, you'll be more resilient to access pattern changes in the Clever API.

Paging

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.1/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.

Limits

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/districts?limit=30 returns at most 30 districts

📘

The maximum limit is 10000 records per page.