Clever Developer Docs

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, https://api.clever.com/v1.2/schools/<id>/students will return all students whose primary school is <CLEVER ID> The diagram for each record type lists associated records. Associated records connected with a solid line are also listed in the record object; records connected with a dotted line must be accessed through a relative link or other endpoint.

Districts

Clever has a district-centric data model – our top level object is the district. Districts contain schools, sections, teachers, students, school_admins, and district_admins

The district object itself has only the name, Clever id, and mdr_number (if assigned) of the district in question. You'll need to use separate endpoints to access the district's data. For example, since each token will give you access to only a single district, you should use https://api.clever.com/v1.2/schools. While contacts, school admins, and district admins are associated with a district, there is no relative link returned for these users on the district endpoint.

Instead, you can use:

  • Student Contacts
    • https://api.clever.com/v1.2/contacts
  • District Admins
    • https://api.clever.com/v1.2/districts/<id>/admins
    • https://api.clever.com/v1.2/district_admins
  • School Admins
    • https://api.clever.com/v1.2/school_admins

Schools

While schools are not the highest-level object in Clever's data model, every student, teacher, and section must be associated with a school. School admin records can be associated with multiple schools!

To access the sections, teachers, or students associated with a school, use these endpoints:

  • `/schools/{school id}/sections
  • `/schools/{school id}/teachers
  • `/schools/{school id}/students

Sections

Sections (analagous to classes) tie teachers and students together.

Each section has a primary school and contains students and teacher objects. But be careful, the students and teachers may have a different primary school than the section. For example, an elementary student may be enrolled in a middle school math class.

You'll notice that the section has a teacher field as well as a list of teachers - the primary teacher's id will always populate the teacher field and be the 0th record in the teachers list. If a section has more than one teacher, additional teachers are listed in the teachers array. We recommend importing all teachers, not just the primary teacher.

District Administrators

District administrators are users who have the ability to manage the data syncing into Clever and share it with applications.

There are no relative links on district admins.

School Administrators

School administrators are not synced from the SIS; they are created via CSV upload to Clever. These users may be associated with multiple schools.

There is no relative link to a school admin's district, but the record contains a district field which lists the district's Clever ID.

Teachers

As you would expect, users with type teachers are typically instructional staff associated with sections. But you should also be aware that districts may include non-instructional staff (e.g. aides, principals, secretaries) as teachers and will likely not be associated with sections.

Students

Student Contacts

Contacts are not directly associated with schools, only to the district and to students.

Important caveats around using student contact data

While we offer student contact information, it is not normalized in the same way that other data is in Clever. Please note:

  • The quality and formatting of student contact data can vary between SISs
  • Contacts are not unique - if two students have the same contact, there will be two contact records with different IDs
  • Contact IDs are not stable - if any data on the contact changes, the contact will be deleted and a new one will be created with a new ID

For more information, check out our page on Student Contacts

Clever's Data Model