Clever Developer Docs

Student Contacts and Guardians

The user record type contacts represents a guardian that is 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.

📘

In v3.0 of our Data API, contacts will now be returned as a user within the district. All contacts will be associated with at least one student but can be associated with multiple. The student_relationships field will provide an array response for every relationship the user has within the SIS (e.g. if a user is listed as parent to two students and an aunt to another, they will have one Clever ID but will receive 3 values in student_relationship response).

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

The Contact User Object

For a list of attributes and a sample response, please refer to the Contacts section of Clever's Data Model.

Student Relationships

student_relationship will return an array of 3 fields: relationship, student, and type. A contact will have a single student_relationship for every instance they appear as a contact within the SIS.

Keeping Contacts stable

It's important to note that the stability of a contact's Clever ID is dependent upon whether that contact has the sis_id field populated in a district's SIS.

  • 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, any change to contact data will delete the contact record and create a new one with a new corresponding Clever ID.

  • Not all SISes 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 work with our districts team to populate this field.

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

❗️

Please note: If the contact does not have an sis_id, then the contact's Clever ID is not stable - if any information changes on the contact record, the record will receive a new Clever ID.

Conversely, if the contact has an sis_id, the Clever ID will remain stable even if data changes on the record.

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.

SFTP

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

contact field

SFTP spec field

name

contact_name

type

contact_type

relationship

contact_relationship

phone

contact_phone

phone_type

contact_phone_type

email

contact_email

sis_id

contact_sis_id

Limitations: Using SFTP limits the number of contacts a student can have 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

PowerSchool

Supported fields

Imports:

  • name
  • type
  • relationship
  • email
  • phone
  • phone_type
  • Father
  • Mother
  • Guardian
  • EmergContacts

Infinite Campus

contact field

SIS field(s)

name

contacts.firstName + " " + contacts.lastName

type

always "other"

relationship

contacts.relationship

email

contacts.email

phone

contacts.cellPhone or contacts.workPhone or contacts.homePhone or contacts.householdPhone

Skyward

contact field

SIS field(s)

name

E1 Full Name

type

always "other"

relationship

E1 Relation Dsc

phone

E1 Pri Phone or E1 Cell Phone

iNOW

contact field

SIS field(s)

name

GuardianFirstName + " " + GuardianLastName

type

"guardian"

phone

GuardianTelephoneNumber

email

GuardianEmailAddress

Limitations: Contacts information from iNOW can sometimes cause sync issues with Clever. For districts experiencing these issues, contact information may be missing entirely. Districts can help alleviate these issues by using our SFTP upload approach instead.

Aeries

contact field

SIS field(s)

name

First Name + " " + Last Name

email

EmailAddress

phone

CellPhone

relationship

RelationshipToStudent

type

ContactOrder

Tyler SIS

We support Emergency and Primary contacts from Tyler SIS.

Emergency contacts:

contact field

SIS Field(s)

name

Em1Name

type

"emergency"

relationship

Em1Relation

phone

Em1Hphone

phone_type

"home"

Primary contacts:

contact field

SIS Field(s)

name

PrntPriName

type

"primary"

relationship

PrntPriRelation

email

PrntPriEmail

phone

PrntPriCell

phone_type

"cell"

Illuminate

Guardians:

contact field

SIS field(s)

name

contact_name_prefix + contact_first_name + contact_middle name + contact_name_suffix

type

legal_guardian (default: "guardian")

email

contact_email_address

phone

primary_phone or mobile_phone_1 or work_phone_1 or home_phone_1

phone_type

cell or work or home depending on which field is used above

Emergency contacts:

contact field

SIS field(s)

name

contact_name_prefix + contact_first_name + contact_middle name + contact_name_suffix

type

emergency_contact (default "emergency")

email

contact_email_address

phone

primary_phone or mobile_phone_1 or work_phone_1 or home_phone_1

phone_type

cell or work or home depending on which field is used above

SchoolInsight

contact field

SIS field(s)

name

Contact First Name + " " + Contact Last Name

type

Contact Custodial Status (default: guardian)

relationship

Contact Relationship

email

Contact Email

phone

Contact Cell Phone or Contact Work Phone or Contact Home Phone or Contact Other Phone

phone_type

cell or work or home depending on which field is used above

Updated 7 months ago


Student Contacts and Guardians


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.