Student Contacts and Guardians

🚧

Quirky Behavior

If your integration relies on knowing the exact relationship a contact has with a student, be sure to upgrade to version 3.0. This version introduces a "student_relationship" field which defines the relationship each contact has with a specific student.

If your integration relies on knowing the exact relationship a contact has with a student, be sure to upgrade to version 3.0. This version introduces a "student_relationship" field which defines the relationship each contact has with a specific student.

A Contact record represents a guardian that is associated with one or more students.

Clever has evolving support for importing Student Contact records from supported student information systems.

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 v2.0 of our Data API, we’ve made some significant improvements to the way student contact data is represented and managed in Clever. As part of this change, we are renaming Student Contacts to simply Contacts. The endpoint has also changed accordingly.

The Contact object

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

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

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 /students/{id}/contacts.

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

Bulk contact data by district

If your application makes heavy use of contact data, you should use Clever's bulk lookup method at GET /contacts.

Our bulk fetch approach supports the starting_after and ending_before parameters, allowing you to paginate through larger collections. As with most Clever collection methods, you may also use the limit parameter to specify up to 10,000 records per request. Standard rate limiting applies.

Contact data by ID

In addition to accessing contact records by student and in bulk by district, you may also now look up individual contact records with GET /contacts/{id} if you already know the corresponding Clever ID — usually to refresh data you've already obtained.

Additionally, you can use GET /contacts/{id}/students and GET /contacts/{id}/district if you've somehow lost track of the associated students or district associated with that contact record.

❗️

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.

Data warnings and required fields

It is now possible to mark contact fields as required. As a result, it is also possible to generate data warnings when districts do not supply this data, or do not have important fields like "email" in their shared contact information. This will help your app identify error cases to build against before syncing a specific district's data. If you would like to set data warnings for student contact information, reach out to your account manager.

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 fieldSFTP spec field
namecontact_name
typecontact_type
relationshipcontact_relationship
phonecontact_phone
phone_typecontact_phone_type
emailcontact_email
sis_idcontact_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 fieldsImports:
name
type
relationship
email
phone
phone_type
Father
Mother
Guardian
EmergContacts

Infinite Campus

contact fieldSIS field(s)
namecontacts.firstName + " " + contacts.lastName
typealways "other"
relationshipcontacts.relationship
emailcontacts.email
phonecontacts.cellPhone or contacts.workPhone or contacts.homePhone or contacts.householdPhone

Skyward

contact fieldSIS field(s)
nameE1 Full Name
typealways "other"
relationshipE1 Relation Dsc
phoneE1 Pri Phone or E1 Cell Phone

iNOW

contact fieldSIS field(s)
nameGuardianFirstName + " " + GuardianLastName
type"guardian"
phoneGuardianTelephoneNumber
emailGuardianEmailAddress

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 fieldSIS field(s)
nameFirst Name + " " + Last Name
emailEmailAddress
phoneCellPhone
relationshipRelationshipToStudent
typeContactOrder

Tyler SIS

We support Emergency and Primary contacts from Tyler SIS.

Emergency contacts:

contact fieldSIS Field(s)
nameEm1Name
type"emergency"
relationshipEm1Relation
phoneEm1Hphone
phone_type"home"

Primary contacts:

contact fieldSIS Field(s)
namePrntPriName
type"primary"
relationshipPrntPriRelation
emailPrntPriEmail
phonePrntPriCell
phone_type"cell"

Illuminate

Guardians:

contact fieldSIS field(s)
namecontact_name_prefix + contact_first_name + contact_middle name + contact_name_suffix
typelegal_guardian (default: "guardian")
emailcontact_email_address
phoneprimary_phone or mobile_phone_1 or work_phone_1 or home_phone_1
phone_typecell or work or home depending on which field is used above

Emergency contacts:

contact fieldSIS field(s)
namecontact_name_prefix + contact_first_name + contact_middle name + contact_name_suffix
typeemergency_contact (default "emergency")
emailcontact_email_address
phoneprimary_phone or mobile_phone_1 or work_phone_1 or home_phone_1
phone_typecell or work or home depending on which field is used above

SchoolInsight

contact fieldSIS field(s)
nameContact First Name + " " + Contact Last Name
typeContact Custodial Status (default: guardian)
relationshipContact Relationship
emailContact Email
phoneContact Cell Phone or Contact Work Phone or Contact Home Phone or Contact Other Phone
phone_typecell or work or home depending on which field is used above

Migrating from v1.2 to 2.0 Contacts

📘

It’s important to note that if you plan to use v2.0 contacts, you must do a full data sync (not only an Events sync) to completely refresh all contact data in your database.

Key Changes

Contacts now have more stable ID

Previously, if any field on a contact changes, for example, a phone number, we delete the contact and create a new one with a new Clever ID.

Now, contacts will retain the same Clever ID when contact info changes. The only case where a contact’s Clever ID will change is if that contact’s sis_id changes (identical to a student or teacher record). This should provide much more stability for contacts, and allow you to better track changes if that’s important to your application.

*If you are using Events, we now generate a contacts.updated event for the contact. More details here.

Contacts can now have multiple students

Previously, every student-contact relationship was represented by its own record, so a guardian with 3 children would appear as 3 separate records in our API (each with its own Clever ID).

Now, contacts have multiple students associated with a single contact object, represented by an array of student IDs.

New normalized fields

In an effort to provide more standardized contact data, we now normalize the following fields:

type - Primary, Secondary, Parent/Guardian, Emergency, Family, Other
phone_type - Cell, Home, Work, Other
relationship - Parent, Grandparent, Self, Aunt/Uncle, Sibling, Other

A Contact record represents a guardian that is associated with one or more students.

Clever has evolving support for importing Student Contact records from supported student information systems.

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 v2.0 of our Data API, we’ve made some significant improvements to the way student contact data is represented and managed in Clever. As part of this change, we are renaming Student Contacts to simply Contacts. The endpoint has also changed accordingly.

The Contact object

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

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

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 /students/{id}/contacts.

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

Bulk contact data by district

If your application makes heavy use of contact data, you should use Clever's bulk lookup method at GET /contacts.

Our bulk fetch approach supports the starting_after and ending_before parameters, allowing you to paginate through larger collections. As with most Clever collection methods, you may also use the limit parameter to specify up to 10,000 records per request. Standard rate limiting applies.

Contact data by ID

In addition to accessing contact records by student and in bulk by district, you may also now look up individual contact records with GET /contacts/{id} if you already know the corresponding Clever ID — usually to refresh data you've already obtained.

Additionally, you can use GET /contacts/{id}/students and GET /contacts/{id}/district if you've somehow lost track of the associated students or district associated with that contact record.

❗️

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.

Data warnings and required fields

It is now possible to mark contact fields as required. As a result, it is also possible to generate data warnings when districts do not supply this data, or do not have important fields like "email" in their shared contact information. This will help your app identify error cases to build against before syncing a specific district's data. If you would like to set data warnings for student contact information, reach out to your account manager.

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 fieldSFTP spec field
namecontact_name
typecontact_type
relationshipcontact_relationship
phonecontact_phone
phone_typecontact_phone_type
emailcontact_email
sis_idcontact_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 fieldsImports:
name
type
relationship
email
phone
phone_type
Father
Mother
Guardian
EmergContacts

Infinite Campus

contact fieldSIS field(s)
namecontacts.firstName + " " + contacts.lastName
typealways "other"
relationshipcontacts.relationship
emailcontacts.email
phonecontacts.cellPhone or contacts.workPhone or contacts.homePhone or contacts.householdPhone

Skyward

contact fieldSIS field(s)
nameE1 Full Name
typealways "other"
relationshipE1 Relation Dsc
phoneE1 Pri Phone or E1 Cell Phone

iNOW

contact fieldSIS field(s)
nameGuardianFirstName + " " + GuardianLastName
type"guardian"
phoneGuardianTelephoneNumber
emailGuardianEmailAddress

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 fieldSIS field(s)
nameFirst Name + " " + Last Name
emailEmailAddress
phoneCellPhone
relationshipRelationshipToStudent
typeContactOrder

Tyler SIS

We support Emergency and Primary contacts from Tyler SIS.

Emergency contacts:

contact fieldSIS Field(s)
nameEm1Name
type"emergency"
relationshipEm1Relation
phoneEm1Hphone
phone_type"home"

Primary contacts:

contact fieldSIS Field(s)
namePrntPriName
type"primary"
relationshipPrntPriRelation
emailPrntPriEmail
phonePrntPriCell
phone_type"cell"

Illuminate

Guardians:

contact fieldSIS field(s)
namecontact_name_prefix + contact_first_name + contact_middle name + contact_name_suffix
typelegal_guardian (default: "guardian")
emailcontact_email_address
phoneprimary_phone or mobile_phone_1 or work_phone_1 or home_phone_1
phone_typecell or work or home depending on which field is used above

Emergency contacts:

contact fieldSIS field(s)
namecontact_name_prefix + contact_first_name + contact_middle name + contact_name_suffix
typeemergency_contact (default "emergency")
emailcontact_email_address
phoneprimary_phone or mobile_phone_1 or work_phone_1 or home_phone_1
phone_typecell or work or home depending on which field is used above

SchoolInsight

contact fieldSIS field(s)
nameContact First Name + " " + Contact Last Name
typeContact Custodial Status (default: guardian)
relationshipContact Relationship
emailContact Email
phoneContact Cell Phone or Contact Work Phone or Contact Home Phone or Contact Other Phone
phone_typecell or work or home depending on which field is used above

Migrating from v1.2 to 2.0 Contacts

📘

It’s important to note that if you plan to use v2.0 contacts, you must do a full data sync (not only an Events sync) to completely refresh all contact data in your database.

Key Changes

Contacts now have more stable ID

Previously, if any field on a contact changes, for example, a phone number, we delete the contact and create a new one with a new Clever ID.

Now, contacts will retain the same Clever ID when contact info changes. The only case where a contact’s Clever ID will change is if that contact’s sis_id changes (identical to a student or teacher record). This should provide much more stability for contacts, and allow you to better track changes if that’s important to your application.

*If you are using Events, we now generate a contacts.updated event for the contact. More details here.

Contacts can now have multiple students

Previously, every student-contact relationship was represented by its own record, so a guardian with 3 children would appear as 3 separate records in our API (each with its own Clever ID).

Now, contacts have multiple students associated with a single contact object, represented by an array of student IDs.

New normalized fields

In an effort to provide more standardized contact data, we now normalize the following fields:

type - Primary, Secondary, Parent/Guardian, Emergency, Family, Other
phone_type - Cell, Home, Work, Other
relationship - Parent, Grandparent, Self, Aunt/Uncle, Sibling, Other