GuidesClever App DashboardAPI Postman CollectionClever AcademySupportStatus
Guides

Users

The User object is a brand new object within Clever's Data Model and is reflected in updates to other objects and endpoints as well. The User object consolidates all user types, namely students, teachers, contacts, district admins, and staff.

User Table

Click to view User table fields

User

FieldGuranteed?Description
idGuaranteedGlobally unique and stable id for all users created by Clever. Used in API calls (ex. /v3.0/users/4fee004cca2e43cf27000007/).
districtGuaranteedGlobally unique and stable id for user's district.
name.firstGuaranteedUser first name
name.lastGuaranteedUser last name
createdGuaranteedResource creation date. UTC time in W3C Date Time Format: YYYY-MM-DDTHH:MM:SS.SSSZ.
last_modifiedGuaranteedLast time resource was updated. Initializes to resource creation date. UTC time in W3C Date Time Format: YYYY-MM-DDTHH:MM:SS.SSSZ.
links.selfGuaranteedStable link to user.
links.districtGuaranteedGets the district for a user.
links.schoolsGuaranteedGets all schools for a user.
links.sectionsGuaranteedGets all sections for a user.
links.myContactsGuaranteedGets all contacts for a student.
links.myTeachersGuaranteedGets all teachers for a student.
links.myStudentsGuaranteedGets all students for a teacher.
emailNot GuaranteedUser's email address
name.middleNot GuaranteedUser's middle name or initial

Student Table

Click to view Student table fields

User (Student)

FieldGuaranteed?Description
roles.student.schoolGuaranteedGlobally unique and stable id for student's primary school.
roles.student.schoolsGuaranteedList of ids of schools this student is associated with.
roles.student.enrollmentsGuaranteedList of school enrollments which include school id and start/end dates based on when the student is in at least one active section at a school.
roles.student.sis_idGuaranteedInternal student identifier from source system. Recommended for use only when matching historical data to new Clever import.
roles.student.student_numberNot GuaranteedSchool or district defined student identifier.
roles.student.state_idNot GuaranteedState student identifier.
roles.student.location.addressNot GuaranteedPrimary student address.
roles.student.location.cityNot GuaranteedPrimary student city.
roles.student.location.stateNot GuaranteedPrimary student state.
roles.student.location.zipNot GuaranteedPrimary student address ZIP.
roles.student.genderNot GuaranteedStudent gender. Possible values ["M","F", "X", ""].
roles.student.dobNot GuaranteedStudent birthdate. MM/DD/YYYY format.
roles.student.gradeNot GuaranteedStudent grade level. Possible values [ "1", … ,"13", "PreKindergarten", "TransitionalKindergarten", "Kindergarten", "InfantToddler", "Preschool", "PostGraduate", "Ungraded", "Other", ""].
roles.student.graduation_yearNot GuaranteedGraduation year provided by district.
roles.student.ell_statusNot GuaranteedStudent English Language Learner (or Limited English Proficiency) status. Possible values ["Y", "N", ""]. Experimental field - may not be covered in all systems.
roles.student.frl_statusNot GuaranteedStudent’s lunch status.
"Free", "Reduced", "Paid", ""
roles.student.iep_statusNot GuaranteedStudent’s special education status.
Supported values: Y N
roles.student.raceNot GuaranteedStudent's race. Possible values: ["Caucasian", "Asian", "Black or African American", "American Indian", "Hawaiian or Other Pacific Islander", "Two or More Races","Unknown", ""].
roles.student.home_languageNot GuaranteedLanguage spoken in the home setting. Possible values: [Supported values: ”English”, ”Albanian”,
”Amharic”, ”Arabic”, ”Bengali”, ”Bosnian”,
”Burmese”, ”Cantonese”, ”Chinese”,
”Dutch”, ”Farsi”, ”French”, ”German”,
”Hebrew”, ”Hindi”, ”Hmong”, ”Ilocano”,
”Japanese”, ”Javanese”, ”Karen”, ”Khmer”,
”Korean”, ”Laotian”, ”Latvian”, ”Malay”,
”Mandarin”, ”Nepali”, ”Oromo”, ”Polish”,
”Portuguese”, ”Punjabi”, ”Romanian”,
”Russian”, ”Samoan”, ”Serbian”, ”Somali”,
”Spanish”, ”Swahili”, ”Tagalog”, ”Tamil”,
”Telugu”, ”Thai”, ”Tigrinya”, ”Turkish”,
”Ukrainian”, ”Urdu”, ”Vietnamese”.]
roles.student.hispanic_ethcnicityNot GuaranteedStudent's Hispanic/Latino ethnicity. Possible values: ["Y", "N", ""].
roles.student.extNot GuaranteedExtension fields where field name and value is defined by the district
roles.student.district_usernameNot GuaranteedStudent's preferred username, specified by district.

Example Object: Student

{
    "data": {
        "created": "2022-11-28T18:46:36.735Z",
        "district": "6385008f69df036e83e984a3",
        "email": "[email protected]",
        "last_modified": "2024-11-04T20:53:03.602Z",
        "name": {
            "first": "Manuel",
            "last": "Brakus",
            "middle": "I"
        },
        "id": "63850203bfb8460546071e62",
        "roles": {
            "student": {
                "credentials": {
                    "district_username": "manuelb70"
                },
                "dob": "10/23/1995",
                "enrollments": [],
                "gender": "M",
                "grade": "12",
                "graduation_year": "",
                "hispanic_ethnicity": "N",
                "location": {
                    "address": "",
                    "city": "",
                    "state": "",
                    "zip": "11211"
                },
                "race": "Two or More Races",
                "school": "63850203bfb8460546071e5e",
                "schools": [
                    "63850203bfb8460546071e5e"
                ],
                "sis_id": "153274070",
                "state_id": "791610984",
                "student_number": "153274070",
                "unweighted_gpa": "",
                "weighted_gpa": "",
                "email": "[email protected]"
            }
        }
    }

📘

Accessing Sensitive Fields

Sensitive data fields such as IEP_status, ELL_status, and FRL_status require additional scopes to access. A Secure Sync integration is also required. Contact [email protected] for assistance.

Teacher User Type

Click to view User(Teacher) table fields

User (Teacher)

TeacherGuaranteed?Description
roles.teacher.legacy_idGuaranteedGlobally unique and stable id for teacher from earlier API version
roles.teacher.schoolGuaranteedGlobally unique and stable id for teacher's primary school.
roles.teacher.schoolsGuaranteedList of ids of schools this teacher is associated with.
roles.teacher.sis_idGuaranteedInternal teacher identifier from source system. Recommended for use only when matching historical data to new Clever import.
roles.teacher.teacher_numberNot GuaranteedDistrict or school assigned teacher identifier.
roles.teacher.state_idNot GuaranteedState teacher identifier.
roles.teacher.extNot GuaranteedExtension fields where field name and value is defined by the district
roles.teacher.titleNot GuaranteedTeacher's title
roles.teacher.credentials.district_usernameNot GuaranteedTeacher's preferred username, specified by district.

Staff User Type

Click to view User(Staff) table fields

User (Staff)

StaffGuaranteed?Description
roles.staff.legacy_idGuaranteedGlobally unique and stable id for staff from earlier API versions
roles.staff.rolesGuaranteedPossible values: ["PortalOnly, "SchoolTechLead"]
roles.staff.schoolsGuaranteedList of ids of schools this staff member is associated with.
roles.staff.staff_idGuaranteedAn identifier provided by the district when syncing or creating this staff member.
roles.staff.titleNot GuaranteedThe staff member's job title, if specified.
roles.staff.departmentNot GuaranteedDepartment provided by the district
roles.staff.extNot GuaranteedExtension fields where field name and value are defined by the district
roles.staff.credentials.district_usernameNot GuaranteedStaff member's preferred username, specified by district.

District Admin User Type

Click to view User(District Admin) table fields

Users (Admin)

District AdminGuaranteed?Description
roles.district_admin.legacy_idGuaranteedGlobally unique and stable id for district administrators from earlier API versions
roles.district_admin.titleNot GuaranteedThe district admin's job title, if specified.

📘

Fields are not returned in a specific order so please ensure that your app does not rely on the order.

Users Object Example

"data":{
    "created":"string",// ObjectID: Globally unique and stable ID for student
    "district":"string",// ObjectID: Globally unique and stable ID for users' district
    "email":"string",//String: Email address provided by district
    "id":"string",//ObjectID: Globally unique and stable ID for User
    "last_modified":"string",// Timestamp: Last time resource was modified
    "name":{
      "first":"string",// String: First name provided by district
      "last":"string",// String: Last name provided by district
      "middle":"string"// String: middle name provided by district
    },
    "roles":{
      "contact":{
        "legacy_id":"string",// Former Clever ID for User record
        "phone":"string",// String: Contact phone number
        "phone_type":"Cell",// String: Phone number type
        "sis_id":"string",// String: Internal identifier for contact assigned by SIS
        "student_relationships":[
          // String: Students the contact has a relationship with
        ]
      },
      "district_admin":{
        "legacy_id":"string",// Former Clever ID for User record
        "title":"string"// String: Title provided by district
      },
      "staff":{
        "credentials": {
          "district_username": "" // String: District-specified username
        },
        "department":"string",// String: Department provided by district
        "ext": {
          // String: Extension field names and values are defined by the district
        },
        "legacy_id":"string",// Former Clever ID for User record
        "roles":[
          "string" // Staff role, either PortalOnly or SchoolTechLead
        ],
        "schools":[
          "string" // All schools this User is associated with
        ],
        "staff_id":"string",// String: Identifier provided by district
        "title":"string",// String: Title provided by district
      },
      "student":{
        "created":"string",// Timestamp: Resource creation date
        "credentials":{
        	"district_username":"string"// String: District-specified student username
        },
        "dob":"string",// String: Student birthdate
        "ell_status":"Y",
        "enrollments": { //For student school enrollment tracking
          "school": "", // ObjectID: Globally unique and stable ID for the school
          "start_date": "", // Date: When student first enrolled in the school in Clever
          "end_date": "", // Date: When student's enrollment in the school ended
        },
        "ext": {
          "": "" // String: Extension field names and values are defined by the district
        },
        "gender":"M",// String: User gender 
        "grade":"InfantToddler",// String: User grade
        "graduation_year":"string",// String: Graduation year provided by district
        "hispanic_ethnicity":"Y",// Boolean: User's hispanic/latino ethnicity
        "last_modified":"string",// Timestamp: Last time resource was modified
        "legacy_id":"string",// Former Clever ID for User record
        "location": {
          "state": "", // String: User state
          "zip": "", // String: User zip
          "address": "", // String: User street address
          "city": "", // String: User city
          "lat": "", // String: User address latitude (Deprecated)
          "lon": "" // String: User address longitude (Deprecated)
       },
       "race":"Caucasian",// String: User race
       "school":"string",// ObjectID: Globally unique and stable ID for the student's primary school
       "schools":[
        // List of ObjectIDs: List of IDs for schools student is associated with
       ],
       "sis_id":"string",// String: Internal student identifier from SIS
       "state_id":"string",// String: State student identifier
       "student_number":"string",// String: Student number provided by district
      },
      "teacher":{
        "created":"string",// Timestamp: Resource initialization date
        "credentials":{
        	"district_username":"string"// String: District-specified username for teacher
       },
        "district":"string",// ObjectID: Globally unique and stable ID for User's district
        "ext": {
          "": "" // String: Extension field names and values are defined by the district
        },
        "last_modified":"string",// Timestamp: Last time resource was updated
        "legacy_id":"string",// Former Clever ID for User record
        "name": {
          "first": "", // String: First name provided by district
          "last": "", // String: Last name provided by district
          "middle": "" // String: Middle name provided by district
        },
        "school":"string",// ObjectID: Globally unique and stable ID for User's primary school
        "schools":[
         // List of ObjectIDs: List of IDs for all schools User is associated with
        ],
        "sis_id":"string",//String: Internal teacher identifier from SIS
        "state_id":"string",// String: State teacher identifier
        "teacher_number":"string",// String: Teacher number provided by district
        "title":"string"// String: Title provided by district
    }
}



📘

Important information about student contact data

While we offer student contact information, it is not normalized in the same way that other data is in Clever. Please note:

  • The quality and formatting of student contact data can vary between SISs
  • Contacts without sis_id populated are not stable - if any data on the contact changes (such as name, email, or phone number), the contact will be deleted and a new one will be created with a new Clever ID.

For more information, check out our page on Contacts

Updated 7 days ago