Districts

Clever has a district-centric data model – our top-level object is the district. Districts contain schools, terms, courses, sections, and users.

FieldGuaranteed?Description
idGuaranteedGlobally unique and stable id for district created by Clever. Used in API calls (ex /v3.0/districts/4fd43cc56d11340000000005 )
nameGuaranteedDistrict (or CMO) name.
sis_typeGuaranteedIndicates the type of SIS this district's data originates from. "sftp" is returned when district data is synced via SFTP or CSV upload. Other string values vary.
launch_dateGuaranteedIndicates when the end-users in the district are able to start logging in to the application. ISO 8601 extended format: YYYY-MM-DD.
links.selfGuaranteedStable link to district.
portal_urlGuaranteedIndicates the URL of the district's Clever portal.
login_methodsGuaranteedIndicates the type of login methods the district supports. Possible set of values: ["Clever Badges", "Canvas", "Clever Passwords", "Google", "LDAP", "SAML", "Other"]
last_syncNot GuaranteedPopulated as long as the district has synced data.
mdr_numberNot GuaranteedMDR number (used for matching district records)
nces_idNot GuaranteedFederal NCES id for school.
errorNot GuaranteedUser-facing string describing a district error state. Typically useful only for district administrators. Should not be used to programmatically determine district status.
stateNot GuaranteedPossible values: ["running", "pending", "error", "paused", "success", ""] Pending means there is an error that the district can fix; Error means there is an error that Clever can fix. Paused means that the district's sync is paused to reflect last year's data.
pause_startNot GuaranteedIndicates when the district's data gets paused to reflect last year's data in the SIS. ISO 8601 extended format: YYYY-MM-DD.
pause_endNot GuaranteedIndicates when the district's data is unpaused to reflect data for the new school year. ISO 8601 extended format: YYYY-MM-DD.
district_contact.districtNot GuaranteedGlobally unique and stable id for school's district.
district_contact.name.firstNot GuaranteedDistrict administrator's first name.
district_contact.name.lastNot GuaranteedDistrict administrator's last name.
district_contact.emailNot GuaranteedDistrict administrator's email.
district_contact.titleNot GuaranteedDistrict administrator's title, if available.
district_contact.idNot GuaranteedGlobally unique and stable id for the district admin.

📘

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




Example District Object

"data":{
    "district_contact":"string",//Object ID: Globally unique and stable ID for district
    "error":"string",// String: Error state
    "id":"string",// ObjectID: Globally unique and stable ID for district created by Clever
    "last_sync":"string",
    "launch_date":"string",
    "login_methods":[
        // List of supported login types
    ],
    "mdr_number":"string",// String: MDR number
    "name":"string",// String: Name provided by district
    "nces_id":"string",//Federal NCES id for district
    "pause_end":"string",// Date: When district's data will be unpaused
    "pause_start":"string",// Date: When district's data will be paused
    "portal_url":"string",//String: URL where users log in to Clever
    "sis_type":"string",// String: Type of SIS district data originates from
    "state":"running",// String: District's sync status
}

484484



Related objects

The district object only has name, Clever id, mdr_number, and nces_id (if assigned) of the district in question. You'll need to use separate endpoints to access the district's data.

  • For example, since each token will give you access to only a single district, you should use https://api.clever.com/v3.0/schools.
  • Although courses, terms, and users with roles of contacts, school admins, and district admins are associated with a district, there is no relative link returned for these users on the district endpoint.

Instead, you can use: