❗️
Clever Complete Agreement Required
This feature is included with a Clever Complete subscription. Sign up here or email your Application Success Manager to learn more.

Clever User IDs (id Field)
Schema: Users
Schema: Users (Student)
Schema: Users (Teacher)
Schema: Users (School Admins/Staff)
Schema: Users (District Admin)
Example Users Object
Example Student Object

Clever User IDs (`id` Field)

Every Clever user is assigned a unique Clever User ID, accessible in the id field of the User object. This identifier is the authoritative, globally unique, and the most consistent way to reference a user across the entire Clever platform.

While districts provide additional identifiers, such as SIS IDs or email addresses, these fields have limitations:

Email addresses may not be present for all users: Clever does not verify user email addresses, and some users may not have an email on record. This is especially true for younger students.
District-managed identifiers are scoped to a single district: sis_id and similar fields are guaranteed to be unique within a district but could potentially overlap across different districts.

It's considered a best practice to always key off the Clever User ID when linking Clever users to accounts in your system. Use district-managed fields like email or sis_id only as supplemental attributes.

☝️
Note:
In rare cases, a user who has been removed from Clever for 300+ days or whose sis_id has changed will be provisioned a new Clever User ID. In these cases, it's expected for this user to be treated as a new Clever user.

Schema: Users

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

Field	Guranteed?	Description
`id`	Guaranteed	Globally unique and stable id for all users created by Clever. Used in API calls (ex. /v3.0/users/4fee004cca2e43cf27000007/).
`district`	Guaranteed	Globally unique and stable id for user's district.
`name.first`	Guaranteed	User first name
`name.last`	Guaranteed	User last name
`created`	Guaranteed	Resource creation date. UTC time in W3C Date Time Format: YYYY-MM-DDTHH:MM:SS.SSSZ.
`last_modified`	Guaranteed	Last time resource was updated. Initializes to resource creation date. UTC time in W3C Date Time Format: YYYY-MM-DDTHH:MM:SS.SSSZ.
`links.self`	Guaranteed	Stable link to user.
`links.district`	Guaranteed	Gets the district for a user.
`links.schools`	Guaranteed	Gets all schools for a user.
`links.sections`	Guaranteed	Gets all sections for a user.
`links.myContacts`	Guaranteed	Gets all contacts for a student.
`links.myTeachers`	Guaranteed	Gets all teachers for a student.
`links.myStudents`	Guaranteed	Gets all students for a teacher.
`email`	Not Guaranteed	User's email address
`name.middle`	Not Guaranteed	User's middle name or initial

Schema: Users (Student)

Field	Guaranteed?	Description
`roles.student.school`	Guaranteed	Globally unique and stable id for student's primary school.
`roles.student.schools`	Guaranteed	List of ids of schools this student is associated with.
`roles.student.enrollments`	Guaranteed	List 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_id`	Guaranteed	Internal student identifier from source system. Recommended for use only when matching historical data to new Clever import.
`roles.student.student_number`	Not Guaranteed	School or district defined student identifier.
`roles.student.state_id`	Not Guaranteed	State student identifier.
`roles.student.location.address`	Not Guaranteed	Primary student address.
`roles.student.location.city`	Not Guaranteed	Primary student city.
`roles.student.location.state`	Not Guaranteed	Primary student state.
`roles.student.location.zip`	Not Guaranteed	Primary student address ZIP.
`roles.student.gender`	Not Guaranteed	Student gender. Possible values ["M","F", "X", ""].
`roles.student.dob`	Not Guaranteed	Student birthdate. MM/DD/YYYY format.
`roles.student.grade`	Not Guaranteed	Student grade level. Possible values [ "1", … ,"13", "PreKindergarten", "TransitionalKindergarten", "Kindergarten", "InfantToddler", "Preschool", "PostGraduate", "Ungraded", "Other", ""].
`roles.student.graduation_year`	Not Guaranteed	Graduation year provided by district.
`roles.student.ell_status`	Not Guaranteed	Student English Language Learner (or Limited English Proficiency) status. Possible values ["Y", "N", ""]. Experimental field - may not be covered in all systems.
`roles.student.frl_status`	Not Guaranteed	Student’s lunch status. "Free", "Reduced", "Paid", ""
`roles.student.iep_status`	Not Guaranteed	Student’s special education status. Supported values: Y N
`roles.student.race`	Not Guaranteed	Student'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_language`	Not Guaranteed	Language 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_ethcnicity`	Not Guaranteed	Student's Hispanic/Latino ethnicity. Possible values: ["Y", "N", ""].
`roles.student.ext`	Not Guaranteed	Extension fields where field name and value is defined by the district
`roles.student.district_username`	Not Guaranteed	Student's preferred username, specified by district.

📘
Additional student demographic fields in API v3.1
API v3.1 adds roles.student.gifted_status, roles.student.section_504_status, roles.student.disability.disability_status, roles.student.disability.disability_type, roles.student.disability.disability_code, and roles.student.home_language_code.
In API v3.1, roles.student.frl_status also adds "Other" as a supported value.

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

Schema: Users (Teacher)

Teacher	Guaranteed?	Description
`roles.teacher.legacy_id`	Guaranteed	Globally unique and stable id for teacher from earlier API version
`roles.teacher.school`	Guaranteed	Globally unique and stable id for teacher's primary school.
`roles.teacher.schools`	Guaranteed	List of ids of schools this teacher is associated with.
`roles.teacher.sis_id`	Guaranteed	Internal teacher identifier from source system. Recommended for use only when matching historical data to new Clever import.
`roles.teacher.teacher_number`	Not Guaranteed	District or school assigned teacher identifier.
`roles.teacher.state_id`	Not Guaranteed	State teacher identifier.
`roles.teacher.ext`	Not Guaranteed	Extension fields where field name and value is defined by the district
`roles.teacher.title`	Not Guaranteed	Teacher's title
`roles.teacher.credentials.district_username`	Not Guaranteed	Teacher's preferred username, specified by district.

Schema: Users (School Admin/Staff)

Staff	Guaranteed?	Description
`roles.staff.legacy_id`	Guaranteed	Globally unique and stable id for staff from earlier API versions
`roles.staff.roles`	Guaranteed	Possible values: ["PortalOnly, "SchoolTechLead"]
`roles.staff.schools`	Guaranteed	List of ids of schools this staff member is associated with.
`roles.staff.staff_id`	Guaranteed	An identifier provided by the district when syncing or creating this staff member.
`roles.staff.title`	Not Guaranteed	The staff member's job title, if specified.
`roles.staff.department`	Not Guaranteed	Department provided by the district
`roles.staff.ext`	Not Guaranteed	Extension fields where field name and value are defined by the district
`roles.staff.credentials.district_username`	Not Guaranteed	Staff member's preferred username, specified by district.

Schema: Users (District Admin)

District Admin	Guaranteed?	Description
`roles.district_admin.legacy_id`	Guaranteed	Globally unique and stable id for district administrators from earlier API versions
`roles.district_admin.title`	Not Guaranteed	The district admin's job title, if specified.

Example Users Object

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

Example Student Object

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

❗️
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

Clever Complete Agreement Required

Table of Contents

Clever User IDs (id Field)

Note:

Schema: Users

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

Schema: Users (Student)

Additional student demographic fields in API v3.1

Accessing Sensitive Fields

Schema: Users (Teacher)

Schema: Users (School Admin/Staff)

Schema: Users (District Admin)

Example Users Object

Example Student Object

Important information about student contact data

Clever User IDs (`id` Field)