Migrating from v2.x Contacts to v3.x 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:

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.