Overview and Best Practices

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.

📘

Testing the API Explorer

Use your API tokens if you have them, or feel free to use our test tokens to explore the API.

Identity API test tokens:

• ilc_DEMO_STUDENT_TOKEN
• ilc_DEMO_TEACHER_TOKEN
• ilc_DEMO_SCHOOL_ADMIN_TOKEN
• ilc_DEMO_DISTRICT_ADMIN_TOKEN

Data API test tokens:

• TEST_TOKEN

Events API test tokens:

• TEST_TOKEN

For relationships between records and our full schema, check out Clever's Data Model.

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

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

📘

The maximum limit is 10000 records per page.