Contacts and Guardians

❗

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].

🚧

Upgrading from v2.x to 3.x?

Please refer to the Migrating from v2.x Contacts to v3.x Contacts for additional guidance on transitioning to the updated API version.

Clever Contacts

The user record type contacts represents a guardian associated with one or more students. The reliability, formatting, and source of student contact information vary depending on the underlying SIS or approach used to communicate this data to Clever.

The Contact User Object

In v3.0 of our Data API, contacts will now be returned as users within the district on the /users endpoint. All contacts will be associated with at least one student but can be associated with multiple through the student_relationships field.

Please refer to the User section of Clever's Data Model for a list of attributes associated with the user object and a sample user record response from /users.

The full contact name will be stored in the last_name field of the user object. This decision was made based on how contacts have been historically ingested in Clever and stored in SISs.

Student Relationships

student_relationship will return an array of three fields: relationship, student, and type. A contact will have a single student_relationship for every instance they appear as a contact within the SIS. For example, if a user is listed as an uncle to two students and a parent to another, they will have one Clever ID but will receive 3 values in the student_relationship response.

Here is an example of a contact record with multiple student relationships:

{
    "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",
        "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"
            }
        }
    }

Keeping Contacts Stable

It's important to note that the stability of a contact's Clever ID is dependent upon a number of factors.

• If the contact record does have an sis_id, the contact will retain the same Clever ID when any contact info changes (for example, phone, email, or name). The only case where a contact’s Clever ID will change is if that contact’s sis_id changes (similar behavior to a student or teacher record).

• If the contact record does not have an sis_id,

  • If contact has name and email, then the contact Clever ID is derived from a concatenation of name + email.
  • If contact doesn't have email but has a name and phone number, then contact Clever ID is derived from a concatenation of name + phone.
  • If they don’t have either email or phone number, then contact Clever ID is derived from a combination of name, contact type, relationship, and phone type.

• Not all SISs have sis_id for contact data. In other cases, the field may exist but is not populated. If you find that districts you work with are missing sis_id for contact data, we recommend you contact the district directly or contact Clever Support to assist the district with updating the data.

Accessing Contacts

📘

Processing student_relationships

Contact information is especially sensitive for privacy and security purposes. Please ensure that the correct relationship is tied to the correct student when assigning privileges in your database.

Syncing Contacts First

If your application focuses on contact data, you should sync through all users within a district using GET /users or add a ?role parameter to filter for contacts. You will then be able to retrieve associated students given a Clever ID by using GET /users/{id}/mystudents.

Contact Data by Student

Clever has offered support for retrieving contact data by student for some time. Given a Clever ID for a specific student, you can retrieve a collection of the contacts associated with that student using GET /users/{id}/mycontacts.

This approach is not recommended for applications requiring all contact data within a district, but works well for ad hoc access patterns.

How Contact Data Varies

In most cases, Clever developers never need to worry about the underlying SIS a district uses. Due to the wide variance in SIS support for contact records, we recommend applications making extensive use of Contacts data to be aware of these particulars and to be extra tolerant of unusual formatting as Clever does not normalize all data from these fields.

Please refer to this article in our Help Center for more detailed information on how student contacts are ingested from a district's SIS into Clever.

SFTP

Districts using our SFTP upload feature can share student contacts as part of the students.csv upload. The following fields are supported:

Limitations: Using SFTP limits a student's number of contacts to 5 contacts maximum. No custom mappings are supported.

SIS-Managed Auto-Sync

Limitations: Contacts field support varies district-to-district.

• contact_relationship is often missing and sometimes you may find contact_type containing data you'd typically look for in contact_relationship
• phone_type cannot be set
• contact.sis_id is supported for Infinite Campus, IC OneRoster API, Skyward, and Skyward API only