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}](🔗) responseRemoved 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 typeNew 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` parameterUsing 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 valuesRemoved 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 typeNew 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` parameterUsing 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` insteadMultipart form data