Clever's Data Model

Here, we'll walk you through how records are related in our data model. You can query for related records using relative links returned in the response unless otherwise noted. For example, /schools/{id}/sections will return all sections whose primary school is {id} The diagram for each record type lists associated records. Associated records connected with a solid line have their IDs listed in the record object; records connected with a dotted line must be accessed through a relative link or other endpoint.

Schema

Below each object, we've added a sample record with available fields - we've sorted the fields for clarity, but they may be returned in any order. Please note the table as well, which outlines which fields are (and are not) guaranteed.

Field formats

Object ID: All Clever IDs take the ObjectID format. We guarantee that ObjectIDs are globally unique across districts and User objects.
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: We normalize dates in Clever to YYYY-MM-DD: "2015-08-25"
Timestamp: Timestamps are expressed in this format: "2015-08-25T00:00:00.000Z"
Boolean: Booleans have a value of either "Y" or "N"

Links

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":"/v3.0/users/4fee004cca2e43cf2700028b" },
    { "rel":"district","uri":"/v3.0/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/v3.0/users/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.

Clever has a district-centric data model – our top-level object is the district. Districts contain schools, terms, courses, sections, and users.