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 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**: 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:
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/v2.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.
## Districts
Clever has a district-centric data model – our top level object is the district. Districts contain schools, terms, courses, sections, teachers, students, school_admins, and district_admins, and contacts.

## District object
### Guaranteed fields
`
id
``
name
``
state
` - Possible values: ["running", "pending", "error", "paused", "success", ""] Pending means there is an error that the district can fix; Error means there is an error that Clever can fix. Paused means that the district's sync is paused to reflect last year's data.`
last_sync
` - Populated as long as the district has synced data`
launch_date
``
goals_enabled
``
portal_url
``
login_methods
`
### Optional fields
`
mdr_number
``
nces_id
``
error
` - User-facing string describing a district error state. Typically useful only for district administrators. Should not be used to programmatically determine district status.`
sis_type
` - Indicates the type of SIS this district's data originates from. "sftp" is returned when district data is synced via SFTP or CSV upload. Other string values vary.`
pause_start
``
pause_end
``
district_contact
`
## Related objects
The district object itself has only the `name
`, Clever `id
`, `mdr_number
`, and `nces_id
` (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/v2.1/schools
`. While courses, terms, 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:
Terms
[/terms](🔗)
Courses
[/courses](🔗)
Contacts
[/contacts](🔗)
District Admins
[/district_admins](🔗)
School Admins
[/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 at least one school. School admin records can be associated with multiple schools!

## School objects
### Guaranteed fields
`
id
``
district
``
name
``
created
``
last_modified
` - Initializes to created date`
sis_id
``
school_number
`
### Optional fields
`
state_id
``
nces_id
``
mdr_number
``
low_grade
` - Possible values [ "1", … ,"13", "PreKindergarten", "TransitionalKindergarten", "Kindergarten", "InfantToddler", "Preschool", "PostGraduate", "Ungraded", "Other", ""]`
high_grade
` - Possible values [ "1", … ,"13", "PreKindergarten", "TransitionalKindergarten", "Kindergarten", "InfantToddler", "Preschool", "PostGraduate", "Ungraded", "Other", ""]`
principal
``
location
``
phone
`[`
ext
`](🔗)
## Related objects
To access the sections, teachers, or students associated with a school, use these endpoints:
[/schools/{id}/sections](🔗)
[/schools/{id}/teachers](🔗)
[/schools/{id}/students](🔗)
## Terms
Terms are an optional data type - these are only created if a district sends us term information.

## Term objects
### Guaranteed fields
`
id
``
district
`At least one of the optional fields listed below
### Optional fields
`
name
``
start_date
``
end_date
`
## Related objects
To retrieve a list of the section objects associated with a term, use [/terms/{id}/sections](🔗).
## Courses
Courses are an optional data type - courses are only created if a district chooses to sync course information to Clever.

## Course objects
### Guaranteed fields
`
id
``
district
`At least one of the optional fields listed below
### Optional fields
`
name
``
number
`
## Related objects
To retrieve a list of the section objects associated with a course, use [/courses/{id}/sections](🔗).
## Sections
Sections (analagous to classes) tie teachers and students together.

## Section objects
### Guaranteed fields
`
id
``
district
``
school
``
created
``
last_modified
``
name
` - Clever generates a section name by concatenating "course_name" "- teacher_last_name" and "- period", e.g. _Algebra - Smith - Period 3_. If course name is not present, the section name from the source system is used.`
sis_id
``
subject
` - Possible values: ["english/language arts","math","science","social studies","language","homeroom/advisory", "interventions/online learning","technology and engineering","PE and health","arts and music","other",""]`
students
``
teacher
``
teachers
`
### Optional fields
`
grade
` - Possible values [ "1", … ,"13", "PreKindergarten", "TransitionalKindergarten", "Kindergarten", "InfantToddler", "Preschool", "PostGraduate", "Ungraded", "Other", ""]`
course
``
term
``
section_number
``
period
`[`
ext
`](🔗)
## Related objects
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
`. 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.
[/sections/{id}/course](🔗)
[/sections/{id}/term](🔗)
[/sections/{id}/students](🔗)
[/sections/{id}/teachers](🔗)
## Students

## Student objects
### Guaranteed fields
`
id
``
district
``
school
``
schools
``
created
``
last_modified
``
sis_id
``
name.first
``
name.last
``
enrollments
`
### Optional fields
`
name.middle
``
email
``
student_number
``
state_id
``
credentials.district_username
``
gender
` - Possible values: ["M", "F"]`
race
` - Possible values: ["Caucasian", "Asian", "Black or African American", "American Indian", "Hawaiian or Other Pacific Islander", "Two or More Races","Unknown", ""]`
hispanic_ethnicity
``
location
``
graduation_year
``
grade
``
home_language
`[`
ext
`](🔗)enrollments
## Related objects
[/students/{id}/schools](🔗)
[/students/{id}/sections](🔗)
[/students/{id}/teachers](🔗)
## 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.

## Teacher objects
### Guaranteed fields
`
id
``
district
``
school
``
schools
``
created
``
last_modified
``
sis_id
``
name.first
``
name.last
`
### Optional fields
`
name.middle
``
email
``
teacher_number
``
state_id
``
title
``
credentials.district_username
`
## Related objects
[/teachers/{id}/schools](🔗)
[/teachers/{id}/sections](🔗)
[/teachers/{id}/sections](🔗)
[/teachers/{id}/students](🔗)
[teachers/{id}/grade_levels](🔗)
## 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.

## School administrator objects
### Guaranteed fields
`
id
``
email
``
district
``
schools
``
created
``
last_modified
``
staff_id
``
name.first
``
name.last
`
### Optional fields
`
department
``
title
`
## Related objects
[/school_admins/{id}/schools](🔗)
## District Administrators
District administrators are users who have the ability to manage the data syncing into Clever and share it with applications.

## District administrator objects
### Guaranteed fields
`
id
``
district
``
name
``
email
`
### Optional fields
`
title
`
## Related objects
There are no relative links on district admins.
## 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 without `
sis_id
` populated are not stable - if any data on the contact changes (such as name, email, or phone number), the contact will be deleted and a new one will be created with a new Clever ID.For more information, check out [our page on Contacts](🔗)

## Contact objects
### Guaranteed fields
Field Name | Format | Description |
`id ` | ObjectID | Globally unique and stable id for contact. |
`district ` | ObjectID | Globally unique and stable ID for contact district |
`name ` | String | Full name provided by the district. |
`type ` | String | Type of contact. Possible values: `Primary `, `Secondary `, `Parent/Guardian `, `Emergency `, `Family `, `Other ` |
`students ` | Array of ObjectIDs | List of student IDs associated with contact. |
### Optional fields
Field Name | Format | Description |
`sis_id ` | String | Internal identifier for contact assigned by SIS. |
`email ` | String | Contact email address. |
`phone ` | String | Contact phone number. |
`phone_type ` | String | Type of phone number. Possible values: `Cell `, `Home `, `Work `, `Other `. |
`relationship ` | String | Relationship to student.
Possible values: `Parent `, `Grandparent `, `Self `, `Aunt/Uncle `, `Sibling `, `Other `. |
## Related objects
[/contacts/{id}/students](🔗)