What's New in API v3.0
Deprecation Notice
On July 31, 2025, Clever will be deprecating the API v2 contacts endpoint. You will need to update your Clever integration to use the contacts endpoint in API v3. There is no planned deprecation for other endpoints in API v2, so your integration can continue using any other API v2 endpoints as desired.
We estimate the migration will take 1-4 weeks depending on your current integration setup and engineering resources.
The API v2 contacts endpoint assigns a single relationship to each contact, which can result in inaccurate or misleading data when a contact is associated with multiple students.
API v3 resolves this issue by allowing contacts to have distinct relationships for each associated student, ensuring accurate and reliable data.If you have questions, please reach out to [email protected].
API v3.0 Changelog
Below is a full changelog of what has changed in API v3.0 (12/20). Please reference our Data Model and our Postman collection pages for further details and the full API schema.
Notable Changes
New User Data Object
API v3.0 introduces /users
as an endpoint bringing students, teachers, staff, district admins, and contacts under one object, individually queryable by adding a role type parameter (e.g., /users?role=teacher
).
Improved Student Contact Relationships
- Student Relationships Array: Contacts now include a
student_relationships
array, detailing all relationships the contact has with students in their district's Student Information System (SIS).- Each entry in the array represents a specific relationship, identified by both the relationship type and the Clever ID of the student.
- For example, if a contact is listed as a parent for two students and an aunt to another, they will have one Clever ID and three entries in the
student_relationships
array.
Learn more here.
New Content/Resource Mapping API
See the changelog below. Learn more here.
Identity API
Click to view the changelog for the Identity API
Changed
- The
type
field on/me
will now return"user"
for any user records instead of a specific role type.
Data API
Click to view the changelog for the Data API
Added
Users record type, which replaces District Admins, Staff (formerly known as School Admins), Teachers, and Students, and associated endpoints:
- GET
/users
role
parameter, which can be used to filter responses to users that have a specific role
- GET
/schools/{id}/users
role
parameter, which can be used to filter responses to users that have a specific role
- GET
/sections/{id}/users
role
parameter, which can be used to filter responses to users that have a specific role
- GET
/users/{id}
- GET
/users/{id}/district
- GET
/users/{id}/schools
- GET
/users/{id}/myteachers
- GET
/users/{id}/mystudents
- GET
/users/{id}/mycontacts
- GET
/users/{id}/sections
- GET
/users/{id}/resources
- Contacts now return
student_relationships
, which defines the Contact'stype
andrelationship
with a specificstudent
. This replaces the previous top-leveltype
andrelationship
fields. - Staff records return
roles
, which shows the permissions this user has in Clever. - Staff records can now be accessed on a per-school basis:
- GET
/schools/{id}/users?role=staff
- GET
- GET
/schools/{id}/users
returns all users for the specified school, even if the school is not the primary school for the user. - Terms and Courses can now be accessed on a per-school basis:
- GET
/schools/{id}/courses
- GET
/schools/{id}/terms
- GET
/courses/{id}/schools
- GET
/terms/{id}/schools
- GET
Changed
- School Admins are now referred to as
Staff
. - GET
/schools/{id}/users
returns all users associated with that school, even if their primary school is not{id}
.
Removed
- School endpoints that reference roles instead of users:
- GET
/schools/{id}/students
, replaced by GET/schools/{id}/users?role=student
- GET
/schools/{id}/teachers
, replaced by GET/schools/{id}/users?role=teacher
- GET
- Section endpoints that reference roles instead of users:
- GET
/sections/{id}/students
, replaced by GET/sections/{id}/users?role=student
- GET
/sections/{id}/teachers
, replaced by GET/sections/{id}/users?role=teacher
- GET
/sections/{id}/teacher
- GET
- Contacts endpoints:
- GET
/contacts
, replaced by GET/users?role=contact
- GET
/contacts/{id}
, replaced by GET/users/{id}
- GET
/contacts/{id}/students
, replaced by GET/users/{id}/mystudents
- GET
/contacts/{id}/district
, replaced by GET/users/{id}/district
- GET
- District Admins endpoints:
- GET
/district_admins
, replaced by GET/users?role=district_admin
- GET
/district_admins/{id}
, replaced by GET/users/{id}
- GET
/district_admins/{id}/district
, replaced by GET/users/{id}/district
- GET
- School Admins endpoints:
- GET
/school_admins
, replaced by GET/users?role=staff
- GET
/school_admins/{id}
, replaced by GET/users/{id}
- GET
/school_admins/{id}/schools
, replaced by GET/users/{id}/schools
- GET
/school_admins/{id}/district
, replaced by GET/users/{id}/district
- GET
- Students endpoints:
- GET
/students
, replaced by GET/users?role=student
- GET
/students/{id}
, replaced by GET/users/{id}
- GET
/students/{id}/contacts
, replaced by GET/users/{id}/mycontacts
- GET
/students/{id}/school
- GET
/students/{id}/schools
, replaced by GET/users/{id}/schools
- GET
/students/{id}/sections
, replaced by GET/users/{id}/sections
- GET
/students/{id}/teachers
, replaced by GET/users/{id}/myteachers
- GET
/students/{id}/district
, replaced by GET/users/{id}/district
- GET
- Teachers endpoints:
- GET
/teachers
, replaced by GET/users?role=teacher
- GET
/teachers/{id}
, replaced by GET/users/{id}
- GET
/teachers/{id}/school
- GET
/teachers/{id}/schools
, replaced by GET/users/{id}/schools
- GET
/teachers/{id}/sections
, replaced by GET/users/{id}/sections
- GET
/teachers/{id}/students
, replaced by GET/users/{id}/mystudents
- GET
/teachers/{id}/district
, replaced by GET/users/{id}/district
- GET
Content Mapping API
The Content Mapping API is new to v3.0. This feature allows districts to indicate via the API which resources should be shared with courses, classes, and users. For ease of understanding, these endpoints are separated here but are part of the Data API in the API explorer.
Click to view the changelog for the Content Mapping API
Added
- Resources record type, which represents a resource owned and controlled by your application, and associated endpoints:
- GET
/resources
- GET
/resources/{id}
- GET
/resources/{id}/courses
- GET
/resources/{id}/sections
- GET
/resources/{id}/users
role
parameter, which can be used to filter responses to users that have a specific role
- GET
Events API
Click to view the changelog for the Events API
Added
- Created/Updated/Deleted events for Users.
Changed
record_type
param also allows "users" value.
Removed
- Created/Updated/Deleted events for role-specific records:
districtadmins.*
, replaced byusers.*
schooladmins.*
, replaced byusers.*
teachers.*
, replaced byusers.*
students.*
, replaced byusers.*
contacts.*
, replaced byusers.*
Updated 18 days ago