Upgrading to API v2.1

🚧

Full Resyncs Ahead!

If you are moving between API versions, we strongly recommend doing a full Data API sync to ensure our databases are in alignment.

Upgrading from v2.0

You can make calls against new versions of the API by updating your URLs (e.g. https://api.clever.com/v2.1/districts).

Instant Login (Identity API) Updates

• Make sure you update your call to the /me endpoint to https://api.clever.com/v2.1/me
• https://api.clever.com/v2.1/me now returns authorized_by: district for usage with the Clever Library.

Data API Updates

• /students now supports school enrollment start and end dates.
• /students now supports non-binary gender value ("X").
• /students now supports a wider range of grade values ("TransitionalKindergarten", "InfantToddler", "Preschool", "13", "Ungraded").
• /sections and /students now support a wider range of grade values ("TransitionalKindergarten", "InfantToddler", "Preschool", "13", "Ungraded").
• /schools now support a wider range of high_grade and low_grade values ("TransitionalKindergarten", "InfantToddler", "Preschool", "13", "Ungraded").
• The /students, /teachers, /sections, and /schools now return extension fields see Extension Fields for more detail.
• /districts now support the following fields: portal_url, login_methods, district_contact, goals_enabled.

The count params can now be used on the following endpoints:

• /districts
• /students
• /teachers
• /sections
• /schools
• /contacts
• /district_admins
• /school_admins
• /terms
• /courses

Upgrading from v1.2

You can make calls against new versions of the API by updating your URLs (e.g. https://api.clever.com/v2.0/districts).

Instant Login (Identity API) Updates

• Make sure you update your call to the /me endpoint to https://api.clever.com/v2.0/me
• https://api.clever.com/v2.0/me no longer returns the full user object for Secure Sync users. All integrations should subsequently call /<user type>/<id> using the Data API (and corresponding district-app token) to access the user object.
• Similarly, for Secure Sync customers, querying /<user type>/<id>/sections using an Instant Login token will no longer return course and term data anymore. Instead, use your corresponding district-app bearer token to make the API request to retrieve this information.

Data API Updates

• Courses are now their own object type. For more details, see Initializing and Syncing Data
• Terms are now their own object type. For more details, see Initializing and Syncing Data
• Contacts are a new object type, replacing the Student Contacts type. Contacts can be associated with multiple students, and are more stable than Student Contacts. We also added some data normalization to contacts - see Student Contacts for more details.
• GET: https://clever.com/oauth/tokens can now be used to query for a specific district's token.
• /districts/{id}/status information has been moved onto the /districts/{id} response
• Removed redundant endpoints:
• /districts/{id}/status - data moved to /districts/{id}
• /districts/{id}/schools - replace with /schools
• /districts/{id}/admins - replace with /district_admins and /school_admins
• /districts/{id}/sections - replace with /sections
• /districts/{id}/students - replace with /students
• /districts/{id}/teachers - replace with /teachers
• /students/{id}/teachers - can now return up to 10 teachers (previous limit of 4)

Events API Updates

• New /events parameters:
• school - allows you to query for events related to a specific school.
• record_type - allows you to filter events by record type
• New event types:
• contacts.created - replaces studentcontacts.created
• contacts.deleted - replaces studentcontacts.deleted
• contacts.updated
• district_admins.created
• district_admins.updated
• district_admins.deleted
• courses.created
• courses.updated
• courses.deleted
• terms.created
• terms.updated
• terms.deleted
• Removed event types:
• studentcontacts.created
• studentcontacts.deleted
• Deprecated parameters:
• where
• type

See the Events page for details.

As a reminder, we're officially deprecating several legacy features that have very little usage. While they are deprecated, we will continue to support the features through June 2018, though no new customers may use these features from now on.

• page parameter
• count parameter
• created_since parameter
• sort parameter
• distinct parameter
• Using the limit parameter with a value greater than 10,000

Upgrading from v1.1

You can make calls against new versions of the API by updating your URLs (e.g. https://api.clever.com/v2.0/districts).

Instant Login (Identity API) Updates

• The https://api.clever.com/me endpoint (primarily used in Instant Login) is for v1.1 only. To receive responses with features from v2.0, you need to update to use https://api.clever.com/v2.0/me.
• https://api.clever.com/v2.0/me no longer returns the full user object for Secure Sync users. All integrations should call /<user type>/<id> using the Data API to access the user object.
• Similarly, for Secure Sync customers, querying /<user type>/<id>/sections using an Instant Login token will no longer return course and term data anymore. Instead, use your corresponding district-app bearer token to make the API request to retrieve this information.

Data API Updates

• Courses are now their own object type. For more details, see Initializing and Syncing Data
• Terms are now their own object type. For more details, see Initializing and Syncing Data
• Contacts are a new object type, replacing the Student Contacts type. Contacts can be associated with multiple students, and are more stable than Student Contacts. We also added some data normalization to contacts - see Student Contacts for more details.
• GET: clever.com/oauth/tokens can now be used to query for a specific district's token.
• /districts/{id}/status information has been moved onto the /districts/{id} response.
• New fields:
• pause_start and pause_end
• launch_date
• status has new values
• Removed redundant endpoints:
• /districts/{id}/status - data moved to /districts/{id}
• /districts/{id}/schools - replace with /schools
• /districts/{id}/admins - replace with /district_admins and /school_admins
• /districts/{id}/sections - replace with /sections
• /districts/{id}/students - replace with /students
• /districts/{id}/teachers - replace with /teachers
• Students and teachers now have the schools field, which returns all schools the record is associated with through sections.
• Students now have the home_language field, which returns a student's home language, if the data is shared with your application.

Events API Updates

• New /events parameters:
• school - allows you to query for events related to a specific school.
• record_type - allows you to filter events by record type
• New event types:
• contacts.created - replaces studentcontacts.created
• contacts.deleted - replaces studentcontacts.deleted
• contacts.updated
• district_admins.created
• district_admins.updated
• district_admins.deleted
• courses.created
• courses.updated
• courses.deleted
• terms.created
• terms.updated
• terms.deleted
• Removed event types:
• studentcontacts.created
• studentcontacts.deleted
• Deprecated parameters:
• where
• type

See the Events page for details.

As a reminder, we're officially deprecating several legacy features that have very little usage. While they are deprecated, we will continue to support the features through June 2018, though no new customers may use these features from now on.

• page parameter
• count parameter
• created_since parameter
• sort parameter
• distinct parameter
• Using the limit parameter with a value greater than 10,000
• api.getclever.com
• api.clever.com/oauth/tokens - use https://clever.com/oauth/tokens instead
• v1.1/push/events endpoint - use v1.1/events instead
• Multipart form data