Migrating from v2.x Contacts to v3.x Contacts
This page will describe high-level considerations when migrating from v2 contacts to v3 contacts.
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].
Overview
With the release of Clever API v3.0, contact data has undergone significant updates. Notably, all contact users now receive a new identifier, the Clever User ID. The previous Clever ID can still be accessed via the legacy_id
field, similar to other user types in Clever.
In addition, to address the case of contacts that are associated with multiple students in different capacities, a student_realtionships
array was introduced. 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.
Follow the guidelines below to update your application to use v3 endpoints for contact data.
Key Changes in v3 Contact Endpoints
The table below highlights the v2.x to v3.x endpoint replacements:
Previous Endpoint | New Endpoint in v3.0 |
---|---|
GET /contacts | GET /users?role=contact |
GET /contacts/{id} | GET /users/{id} |
GET /contacts/{id}/students | GET /users/{id}/mystudents |
GET /contacts/{id}/district | GET /users/{id}/district |
GET /students/{id}/contacts | GET /users/{id}/mycontacts |
New Data Structure for 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.
Important Consideration
Ensure each relationship entry in
student_relationships
is accurately tied to the correct student ID when managing privileges in your database
Example Contact Record
A sample contact data response in v3.0 includes:
{
"data": {
"created": "2022-11-28T18:46:36.819Z",
"district": "6385008f69df036e83e984a3",
"email": "[email protected]",
"last_modified": "2024-11-04T21:05:06.631Z",
"name": {
"last": "Aaron Collins"
},
"id": "63850203bfb8460546071ef6", //Clever API v3.x ID
"roles": {
"contact": {
"phone": "1-(330) 280-1898",
"phone_type": "Other",
"sis_id": "",
"student_relationships": [
{
"relationship": "Aunt/Uncle",
"student": "63850203bfb8460546071e62",
"type": "Family"
},
{
"relationship": "Aunt/Uncle",
"student": "672936fc65fc4500ced13260",
"type": "Family"
},
{
"relationship": "Parent",
"student": "63850203bfb8460546071e6e",
"type": "Parent/Guardian"
}
],
"legacy_id": "63850203bfb8460546071e7e" //Clever API v2.x ID
}
}
},
"uri": "/v3.0/users/63850203bfb8460546071ef6"
},
This example demonstrates the structure of a contact's data in API v3.0. The student_relationships
array lists each relationship the contact has with specific students, identified by both the relationship
type and the student's Clever ID (student
).
By following these guidelines, you’ll ensure a smooth transition to API v3.0 for contact data in your application. If you encounter any issues, consult the linked documentation or reach out to our support team.
See below for additional resources on upgrading to API v3.0 and the v3.0 user object changes.
Updated 9 days ago