Delta-sync event stream API that notifies application partners of changes to roster data (creates, updates, deletes) within a district. Must be enabled via the application dashboard and uses a district-app token for access, enabling efficient incremental data synchronization.
openapi: 3.0.0
info:
description: The Clever Events API
title: Events API
version: 3.1.0
paths:
/events:
get:
description: Returns a list of events
operationId: getEvents
parameters:
- in: query
name: limit
schema:
type: integer
- in: query
name: starting_after
schema:
type: string
- in: query
name: ending_before
schema:
type: string
- in: query
name: school
schema:
type: string
- in: query
name: record_type
explode: true
schema:
type: array
items:
type: string
responses:
"200":
description: OK Response
content:
application/json:
schema:
$ref: "#/components/schemas/EventsResponse"
"404":
$ref: "#/components/responses/NotFound"
tags:
- Events
"/events/{id}":
get:
description: Returns the specific event
operationId: getEvent
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
"200":
description: OK Response
content:
application/json:
schema:
$ref: "#/components/schemas/EventResponse"
"404":
$ref: "#/components/responses/NotFound"
tags:
- Events
security:
- oauth: []
x-samples-languages:
- curl
- node
- ruby
- python
- php
- java
- go
servers:
- url: https://api.clever.com/v3.1
components:
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequest"
InternalError:
description: Internal Error
content:
application/json:
schema:
$ref: "#/components/schemas/InternalError"
NotFound:
description: Entity Not Found
content:
application/json:
schema:
$ref: "#/components/schemas/NotFound"
securitySchemes:
oauth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://clever.com/oauth/authorize
tokenUrl: https://clever.com/oauth/tokens
scopes: {}
schemas:
BadRequest:
properties:
message:
type: string
type: object
Contact:
properties:
legacy_id:
type: string
x-validation: true
phone:
type: string
nullable: true
phone_type:
enum:
- Cell
- Home
- Work
- Other
- ""
type: string
x-validation: true
nullable: true
sis_id:
type: string
nullable: true
student_relationships:
items:
$ref: "#/components/schemas/StudentRelationship"
type: array
x-validation: true
type: object
Course:
properties:
district:
type: string
x-validation: true
id:
type: string
x-validation: true
name:
type: string
nullable: true
number:
type: string
nullable: true
type: object
CourseObject:
properties:
object:
$ref: "#/components/schemas/Course"
type: object
CourseResponse:
properties:
data:
$ref: "#/components/schemas/Course"
type: object
CoursesResponse:
properties:
data:
items:
$ref: "#/components/schemas/CourseResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
Credentials:
properties:
district_username:
type: string
type: object
Disability:
properties:
disability_code:
enum:
- aut
- db
- dd
- emn
- hi
- id
- md
- oi
- other
- ohi
- sld
- sli
- tbi
- vi
type: string
nullable: true
disability_status:
enum:
- Y
- N
- ""
type: string
nullable: true
disability_type:
enum:
- Autism
- Deaf-blindness
- Developmental delay
- Emotional disturbance
- Hearing impairment
- Intellectual Disability
- Multiple disabilities
- Orthopedic impairment
- Other
- Other health impairment
- Specific learning disability
- Speech or language impairment
- Traumatic brain injury
- Visual impairment
type: string
nullable: true
type: object
District:
properties:
district_contact:
$ref: "#/components/schemas/DistrictContact"
error:
type: string
id:
type: string
x-validation: true
last_attendance_sync:
format: datetime
type: string
x-validation: true
nullable: true
last_sync:
format: datetime
type: string
x-validation: true
nullable: true
launch_date:
format: date
type: string
x-validation: true
lms_state:
enum:
- initial_sync_processing
- pending_authorization
- matching_in_progress
- error
- disconnected
- ""
- success
type: string
x-validation: true
nullable: true
lms_type:
enum:
- canvas
- schoology
- google_classroom
- ""
type: string
x-validation: true
nullable: true
login_methods:
items:
type: string
type: array
x-validation: true
mdr_number:
type: string
nullable: true
name:
type: string
nces_id:
type: string
nullable: true
pause_end:
format: datetime
type: string
x-validation: true
nullable: true
pause_start:
format: datetime
type: string
x-validation: true
nullable: true
portal_url:
type: string
sis_type:
type: string
x-validation: true
state:
enum:
- running
- pending
- error
- paused
- ""
- success
type: string
x-validation: true
nullable: true
type: object
DistrictAdmin:
properties:
legacy_id:
type: string
x-validation: true
title:
type: string
nullable: true
type: object
DistrictContact:
properties:
district:
type: string
x-validation: true
email:
type: string
nullable: true
id:
type: string
x-validation: true
name:
$ref: "#/components/schemas/Name"
title:
type: string
x-validation: true
type: object
DistrictObject:
properties:
object:
$ref: "#/components/schemas/District"
type: object
DistrictResponse:
properties:
data:
$ref: "#/components/schemas/District"
type: object
DistrictsResponse:
properties:
data:
items:
$ref: "#/components/schemas/DistrictResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
Event:
discriminator:
propertyName: type
properties:
created:
format: datetime
type: string
x-validation: true
id:
type: string
x-validation: true
type:
type: string
x-validation: true
required:
- type
type: object
EventResponse:
properties:
data:
$ref: "#/components/schemas/Event"
type: object
EventsResponse:
properties:
data:
items:
$ref: "#/components/schemas/EventResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
InternalError:
properties:
message:
type: string
type: object
Link:
properties:
rel:
enum:
- next
- prev
- self
type: string
uri:
type: string
type: object
LmsStatus:
properties:
synced_in_lms:
type: boolean
type: object
Location:
properties:
address:
type: string
nullable: true
city:
type: string
nullable: true
lat:
type: string
nullable: true
lon:
type: string
nullable: true
state:
type: string
nullable: true
zip:
type: string
nullable: true
type: object
Name:
properties:
first:
type: string
nullable: true
last:
type: string
nullable: true
middle:
type: string
nullable: true
type: object
NotFound:
properties:
message:
type: string
type: object
PreferredName:
properties:
first:
type: string
nullable: true
last:
type: string
nullable: true
middle:
type: string
nullable: true
type: object
Principal:
properties:
email:
type: string
nullable: true
name:
type: string
nullable: true
type: object
Resource:
properties:
created:
format: date-time
type: string
district:
type: string
id:
type: string
resource_id:
type: string
roles:
items:
enum:
- teacher
- student
type: string
type: array
title:
type: string
updated:
format: date-time
type: string
type: object
ResourceObject:
properties:
object:
$ref: "#/components/schemas/Resource"
type: object
ResourceResponse:
properties:
data:
$ref: "#/components/schemas/Resource"
type: object
ResourcesResponse:
properties:
data:
items:
$ref: "#/components/schemas/ResourceResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
Roles:
properties:
contact:
$ref: "#/components/schemas/Contact"
district_admin:
$ref: "#/components/schemas/DistrictAdmin"
staff:
$ref: "#/components/schemas/Staff"
student:
$ref: "#/components/schemas/Student"
teacher:
$ref: "#/components/schemas/Teacher"
School:
properties:
created:
format: datetime
type: string
x-validation: true
district:
type: string
x-validation: true
ext:
type: object
high_grade:
enum:
- InfantToddler
- Preschool
- PreKindergarten
- TransitionalKindergarten
- Kindergarten
- "1"
- "2"
- "3"
- "4"
- "5"
- "6"
- "7"
- "8"
- "9"
- "10"
- "11"
- "12"
- "13"
- PostGraduate
- Ungraded
- Other
- ""
type: string
x-validation: true
nullable: true
id:
type: string
x-validation: true
last_modified:
format: datetime
type: string
x-validation: true
location:
$ref: "#/components/schemas/Location"
low_grade:
enum:
- InfantToddler
- Preschool
- PreKindergarten
- TransitionalKindergarten
- Kindergarten
- "1"
- "2"
- "3"
- "4"
- "5"
- "6"
- "7"
- "8"
- "9"
- "10"
- "11"
- "12"
- "13"
- PostGraduate
- Ungraded
- Other
- ""
type: string
x-validation: true
nullable: true
mdr_number:
type: string
nullable: true
name:
type: string
nces_id:
type: string
nullable: true
phone:
type: string
nullable: true
principal:
$ref: "#/components/schemas/Principal"
school_number:
type: string
sis_id:
type: string
state_id:
type: string
nullable: true
type: object
SchoolEnrollment:
properties:
end_date:
format: datetime
type: string
x-validation: true
school:
type: string
x-validation: true
start_date:
format: datetime
type: string
x-validation: true
type: object
SchoolObject:
properties:
object:
$ref: "#/components/schemas/School"
type: object
SchoolResponse:
properties:
data:
$ref: "#/components/schemas/School"
type: object
SchoolsResponse:
properties:
data:
items:
$ref: "#/components/schemas/SchoolResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
Section:
properties:
course:
type: string
x-validation: true
nullable: true
created:
format: datetime
type: string
x-validation: true
district:
type: string
x-validation: true
ext:
type: object
grade:
enum:
- InfantToddler
- Preschool
- PreKindergarten
- TransitionalKindergarten
- Kindergarten
- "1"
- "2"
- "3"
- "4"
- "5"
- "6"
- "7"
- "8"
- "9"
- "10"
- "11"
- "12"
- "13"
- PostGraduate
- Ungraded
- Other
- ""
type: string
x-validation: true
nullable: true
id:
type: string
x-validation: true
last_modified:
format: datetime
type: string
x-validation: true
lms_status:
$ref: "#/components/schemas/LmsStatus"
name:
type: string
period:
type: string
nullable: true
school:
type: string
x-validation: true
section_number:
type: string
nullable: true
sis_id:
type: string
students:
items:
type: string
type: array
x-validation: true
subject:
enum:
- english/language arts
- math
- science
- social studies
- language
- homeroom/advisory
- interventions/online learning
- technology and engineering
- PE and health
- arts and music
- other
- ""
type: string
x-validation: true
nullable: true
teacher:
type: string
x-validation: true
nullable: true
teachers:
items:
type: string
type: array
x-validation: true
term_id:
type: string
x-validation: true
nullable: true
type: object
SectionObject:
properties:
object:
$ref: "#/components/schemas/Section"
type: object
SectionResponse:
properties:
data:
$ref: "#/components/schemas/Section"
type: object
SectionsResponse:
properties:
data:
items:
$ref: "#/components/schemas/SectionResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
Staff:
properties:
credentials:
$ref: "#/components/schemas/Credentials"
department:
type: string
nullable: true
ext:
type: object
legacy_id:
type: string
x-validation: true
roles:
items:
type: string
type: array
x-validation: true
schools:
items:
type: string
type: array
x-validation: true
staff_id:
type: string
title:
type: string
nullable: true
type: object
Student:
properties:
created:
format: datetime
type: string
x-validation: true
credentials:
$ref: "#/components/schemas/Credentials"
disability:
$ref: "#/components/schemas/Disability"
dob:
pattern: (?:[0-9]{1,2})/([0-9]{1,2})/([0-9]{4})
type: string
x-validation: true
nullable: true
ell_status:
enum:
- Y
- N
- ""
type: string
x-validation: true
nullable: true
enrollments:
items:
$ref: "#/components/schemas/SchoolEnrollment"
type: array
x-validation: true
ext:
type: object
frl_status:
enum:
- Free
- Reduced
- Paid
- Other
- ""
type: string
x-validation: true
nullable: true
gender:
enum:
- M
- F
- X
- ""
type: string
x-validation: true
nullable: true
gifted_status:
enum:
- Y
- N
- ""
type: string
x-validation: true
nullable: true
grade:
enum:
- InfantToddler
- Preschool
- PreKindergarten
- TransitionalKindergarten
- Kindergarten
- "1"
- "2"
- "3"
- "4"
- "5"
- "6"
- "7"
- "8"
- "9"
- "10"
- "11"
- "12"
- "13"
- PostGraduate
- Ungraded
- Other
- ""
type: string
x-validation: true
nullable: true
graduation_year:
type: string
x-validation: true
nullable: true
hispanic_ethnicity:
enum:
- Y
- N
- ""
type: string
x-validation: true
nullable: true
home_language:
enum:
- Kannada
- Icelandic
- Shona
- Hmong
- Zulu
- Malay
- Estonian
- Quechua
- Fijian
- Slovenian
- Swedish
- Inuinnaqtun
- Yucatec Maya
- Tamil
- Nepali
- Cantonese
- Arabic
- Welsh
- Gujarati
- Tigrinya
- Dutch
- Queretaro Otomi
- Indonesian
- Lingala
- Kazakh
- Somali
- Yoruba
- Bhojpuri
- Javanese
- Other
- Hawaiian
- Portuguese
- Twi
- Igbo
- Tsonga
- Upper Sorbian
- Belarusian
- Thai
- Faroese
- Lithuanian
- Georgian
- Sindhi
- Albanian
- Haitian Creole
- Hausa
- Azerbaijani
- Tongan
- Cabo Verdean
- Corsican
- Uzbek
- Russian
- Greek
- Hungarian
- Guarani
- Kirundi
- Mizo
- Divehi
- Pashto
- Ewe
- English
- Bengali
- Maithili
- Irish
- Bashkir
- Inuktitut
- Maori
- Tatar
- Hebrew
- Punjabi
- Chinese
- Krio
- Khmer
- Setswana
- Oromo
- Tagalog
- Armenian
- Konkani
- Urdu
- Karen
- Mandarin
- Marshallese
- Turkish
- Ilocano
- Chuukese
- Croatian
- Spanish
- Scots Gaelic
- Mongolian
- Serbian
- Chichewa
- Dari
- Korean
- Cebuano
- Afrikaans
- French
- Macedonian
- Laotian
- Malayalam
- Samoan
- Tibetan
- Aymara
- Italian
- Yiddish
- Telugu
- Norwegian
- Tajik
- Lower Sorbian
- German
- Sundanese
- Bosnian
- Luxembourgish
- Turkmen
- Kurdish (Kurmanji)
- Amharic
- Bambara
- Sinhala
- Farsi
- Finnish
- Catalan
- Frisian
- Odia
- Marathi
- Vietnamese
- Ukrainian
- Czech
- Luganda
- Galician
- Basque
- Kurdish (Sorani)
- Romanian
- Uyghur
- Tahitian
- Bulgarian
- Hindi
- Japanese
- Burmese
- Dogri
- Xhosa
- Latvian
- Polish
- Manipuri
- Danish
- Sesotho
- Filipino
- Northern Sotho
- Assamese
- Kinyarwanda
- Swahili
- Malagasy
- Maltese
- Kyrgyz
- Slovak
type: string
x-validation: true
nullable: true
home_language_code:
enum:
- knn
- uig
- bam
- div
- msa
- sna
- swa
- ces
- kaz
- tsn
- tam
- xho
- cos
- est
- isl
- pus
- slk
- twi
- ibo
- iku
- mlg
- sot
- tah
- mai
- mri
- orm
- slv
- swe
- tso
- bul
- tur
- ceb
- hin
- kat
- som
- bod
- kur
- snd
- tat
- yor
- fas
- heb
- lug
- hsb
- sqi
- glg
- khm
- mlt
- spa
- gle
- gla
- bel
- bho
- nld
- ewe
- deu
- hat
- tgl
- eus
- hau
- jav
- aym
- fil
- fry
- ita
- lav
- mni
- mon
- ron
- chk
- hrv
- uzb
- afr
- ilo
- nso
- pol
- otq
- yid
- fra
- ckb
- sun
- other
- fin
- nep
- pan
- rus
- amh
- nya
- ell
- hun
- ikt
- mkd
- que
- tel
- bos
- ind
- tha
- eng
- prs
- jpn
- nob
- ori
- hye
- aze
- cat
- grn
- run
- kir
- lao
- lit
- mya
- yue
- dgo
- ltz
- cmn
- mar
- mah
- lus
- ben
- zho
- hmn
- kar
- kor
- tgk
- ton
- vie
- asm
- cpp
- kan
- tuk
- ukr
- urd
- zul
- ara
- bak
- dan
- fao
- kin
- lin
- srp
- cym
- fij
- guj
- kri
- mal
- sin
- yua
- haw
- dsb
- por
- smo
- tir
type: string
x-validation: true
nullable: true
iep_status:
type: string
nullable: true
last_modified:
format: datetime
type: string
x-validation: true
legacy_id:
type: string
x-validation: true
location:
$ref: "#/components/schemas/Location"
preferred_name:
$ref: "#/components/schemas/PreferredName"
race:
enum:
- Caucasian
- Asian
- Black or African American
- American Indian
- Hawaiian or Other Pacific Islander
- Two or More Races
- Unknown
- ""
type: string
x-validation: true
nullable: true
school:
type: string
x-validation: true
schools:
items:
type: string
type: array
x-validation: true
section_504_status:
enum:
- Y
- N
- ""
type: string
x-validation: true
nullable: true
sis_id:
type: string
state_id:
type: string
nullable: true
student_number:
type: string
nullable: true
type: object
StudentRelationship:
properties:
relationship:
enum:
- Parent
- Grandparent
- Self
- Aunt/Uncle
- Sibling
- Other
- ""
type: string
x-validation: true
nullable: true
student:
type: string
x-validation: true
type:
enum:
- Parent/Guardian
- Emergency
- Primary
- Secondary
- Family
- Other
- ""
type: string
x-validation: true
nullable: true
type: object
Teacher:
properties:
created:
format: datetime
type: string
x-validation: true
credentials:
$ref: "#/components/schemas/Credentials"
district:
type: string
x-validation: true
ext:
type: object
last_modified:
format: datetime
type: string
x-validation: true
legacy_id:
type: string
x-validation: true
name:
$ref: "#/components/schemas/Name"
school:
type: string
x-validation: true
schools:
items:
type: string
type: array
x-validation: true
sis_id:
type: string
state_id:
type: string
nullable: true
teacher_number:
type: string
nullable: true
title:
type: string
nullable: true
type: object
Term:
properties:
district:
type: string
x-validation: true
end_date:
format: datetime
type: string
x-validation: true
nullable: true
id:
type: string
x-validation: true
name:
type: string
nullable: true
start_date:
format: datetime
type: string
x-validation: true
nullable: true
type: object
TermObject:
properties:
object:
$ref: "#/components/schemas/Term"
type: object
TermResponse:
properties:
data:
$ref: "#/components/schemas/Term"
type: object
TermsResponse:
properties:
data:
items:
$ref: "#/components/schemas/TermResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
User:
properties:
created:
format: datetime
type: string
x-validation: true
district:
type: string
x-validation: true
email:
type: string
nullable: true
id:
type: string
x-validation: true
last_modified:
format: datetime
type: string
x-validation: true
lms_status:
$ref: "#/components/schemas/LmsStatus"
name:
$ref: "#/components/schemas/Name"
roles:
$ref: "#/components/schemas/Roles"
type: object
UserObject:
properties:
object:
$ref: "#/components/schemas/User"
type: object
UserResponse:
properties:
data:
$ref: "#/components/schemas/User"
type: object
UsersResponse:
properties:
data:
items:
$ref: "#/components/schemas/UserResponse"
type: array
links:
items:
$ref: "#/components/schemas/Link"
type: array
type: object
courses.created:
allOf:
- $ref: "#/components/schemas/Event"
- properties:
data:
$ref: "#/components/schemas/CourseObject"
type: object
courses.deleted:
allOf:
- $ref: "#/components/schemas/Event"
- properties:
data:
$ref: "#/components/schemas/CourseObject"
type: object
courses.updated:
allOf:
- $ref: "#/components/schemas/Event"
- properties:
data:
$ref: "#/components/schemas/CourseObject"
previous_attributes:
additionalProperties:
type: object
type: object
districts.created:
allOf:
- $ref: "#/components/schemas/Event"
- properties:
data:
$ref: "#/components/schemas/DistrictObject"
type: object
districts.deleted:
allOf:
- $ref: "#/components/schemas/Event"
- properties:
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clever/refs/heads/main/openapi/clever-events-api-openapi.yml