Clever Developer Docs

Upgrading to API v2.0

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.

If you are using events or student contacts, you must do a full data sync in order to upgrade to v2.0

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

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:
  • 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

Upgrading to API v2.0