Help Center

Using School Passport

APIs

Events API v1

This article provides an overview of the Events API schema.

In this article

Revisions

1. OAuth 2 authorization - “Client credentials” grant

2. Events API endpoints

3. Supported types (“eventType”) of Event data

4. Pagination

5. Supported request parameters

6. Extensions to One Roster data model

7. Format of API responses

7.1 JSON format of a generic response

7.2 JSON format of a Created type of Event data

7.3 JSON format of a Updated type of Event data

7.4 JSON format of a Deleted type of Event data

7.5 JSON format of an Enrollment Event data

Revisions

Document version	Change Description	Effective Date
1.2	Added note that "before" and "after" parameters are uses only for "/events" endpoint for #5.	May 15, 2024
1.1	"User.Enrolled" and "User.Unenrolled" eventType values are replaced with Enrollment.Created & Enrollment.Deleted respectively	Apr 30, 2020
1.0	Initial release	Jan 15, 2020

1. OAuth 2 authorization - “Client credentials” grant

Request:

The request must contain WWW BASIC authorization with client_id and client secret key in request header: ‘Authorization’: ‘Basic {data}’

where data = Base64.encode(‘{client_id}:{client secret}’)

POST

datahub/oauth/token

The endpoint to authenticate a client

Parameter	Mode	Type	Description
grant_type	Required	String	The type of the response (should be: ‘client_credentials’)

Example:

Method	POST
URL	https://{hostname}/datahub/oauth/token
Body	grant_type=client_credentials
Headers	Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0

Response:

The API returns the following response on successful authentication:

{
  "access_token": "zyx",
  "token_type": "bearer",
  "expires_in": 7199
}

Field	Type	Description
access_token	String	OAuth 2.0 Access Token
token_type	String	Token type, which is always 'bearer.’
expires_in	Integer	Expiration time in seconds
scope	String	List of scopes that define data access level

2. Events API endpoints

The base path for Events API v1.1 is /datahub/services/ims/oneroster/v1p1

GET	/events	Gets a list of all events that have occurred within data you have access to
GET	/orgs/{id}/events	Retrieves events for an organization
GET	/schools/{id}/events	Retrieves events for a school data object
GET	/academicSessions/{id}/events	Retrieves events for an academic session
GET	/classes/{id}/events	Retrieves events for a class
GET	/courses/{id}/events	Retrieves events for a course
GET	/teachers/{id}/events	Retrieves events for a teacher
GET	/students/{id}/events	Retrieves events for a student
GET	/terms/{id}/events	Retrieves events for a term
GET	/users/{id}/events	Retrieves events for a user
GET	/demographics/{id}/events	Retrieves events for demographics

3. Supported types (“eventType”) of Event data

Created

Updated

Deleted

AcademicSession.Created

Contact.Created

Course.Created

Class.Created

Demographic.Created

District.Created

Enrollment.Created

School.Created

Student.Created

Teacher.Created

AcademicSession.Updated

Contact.Updated

Course.Updated

Class.Updated

Demographic.Updated

District.Updated

Enrollment.Updated

School.Updated

Student.Updated

Teacher.Updated

AcademicSession.Deleted

Contact.Deleted

Course.Deleted

Class.Deleted

Demographic.Deleted

District.Deleted

Enrollment.Deleted

Student.Deleted

School.Deleted

Teacher.Deleted

4. Pagination

Every response has a “Link” HTTP header element that contains URLs to retrieve the next and the previous page of data. The format of that data: {uri_prev}; rel=“prev”, {uri_next}; rel=“next”

Value of “rel”	Description
self	Corresponds to a URI that was sent for this request
prev	Corresponds to a URI to retrieve the previous “page” of data
next	Corresponds to a URI to retrieve the next “page” of data

5. Supported request parameters

Parameter	Mode	Type	Description
access_token	Required	String	The access token obtained during authorization
after	Optional	Number	Only for "/events" endpoint. {miliseconds_from_epoch} Example=1548944937314
before	Optional	Number	Only for "/events" endpoint. {miliseconds_from_epoch} Example=1548944937314
since	Optional	ISO 8601	Example: since=2020-01-20T16:35:04.084Z Support for “since” query parameter is being deprecated. GG4L encourages use of the “after” parameter instead.
limit	Optional	Number	Max records returned (default 100). The maximum value for limit is 500
offset	Optional	Number	The index of the first record to return (zero indexed) GG4L encourages use of “Link” HTTP header values for navigation through a paginated data (see “Pagination” section).

For example:

GET https://hostname/students?limit=10 - return the first 10 resources in a collection of students.

GET https://hostname/students?limit=10&offset=10 - return the second 10 resources in a collection of students.

6. Extensions to One Roster dataUsers model

Metadata (Yes/No) - whether extension is a part of One Roster metadata.

Metadata	Attribute	Description
Yes	gg4l.home_phone	User’s home phone number
Yes	gg4l.work_phone	User’s work phone number
Yes	gg4l.preferred_contact_method	Supported values: "email", "mobile_phone", "home_phone", "work_phone"
Yes	primaryGrade	Returns the primary grade for students
Yes	gg4l.primarySchool	Returns the primary schools for students and teachers

Demographics

Metadata	Attribute	Description
Yes	gg4l.preferred_language	User’s preferred language (as in SIS/LMS)

7. Format of API responses

7.1. JSON format of a generic response

{
  "events": [
    {
      "sourcedId": "string",
      "timestamp": "string",
      "eventType": "AcademicSession.Created",
      "object": {
        "dateLastModified": "string",
        "sourcedId": "string",
        "status": "string"
      },
      "changes": {
        "dateLastModified": "string",
        "sourcedId": "string",
        "status": "string"
      }
    }
    … 

    {JSON_of_the_last_event_object}
  ]
}

7.2. JSON format of a Created type of Event data

{
  "sourcedId": "17764f9c-7148-4310-b9ba-62f2365d1b5d",
  "eventType": "Teacher.Created",
  "timestamp": "2020-01-09T13:56:06.909Z",
  "object": {
    "sourcedId": "68dffad5-a464-4d47-a00f-b4dbd92ba07d",
    "status": "active",
    "dateLastModified": "2020-01-09T13:56:06.909Z",
    "metadata": {
      "gg4l.primary_school": "5dfcf075-c905-401e-9119-7c5331410dec",
      "gg4l.preferred_contact_method": "email"
    },
    "username": "74115385",
    "userIds": [
      {
        "type": "ORid",
        "identifier": "98124"
      },
      {
        "type": "sftp_id",
        "identifier": "staff_01"
      },
      {
        "type": "statID",
        "identifier": "staff_01"
      }
    ],
    "enabledUser": "false",
    "givenName": "Nette",
    "familyName": "Notkent",
    "middleName": "Nett",
    "role": "teacher",
    "identifier": "032134154",
    "email": "nette.notken@tesmail.com",
    "sms": "0212234654",
    "phone": "0212234654",
    "orgs": [
      {
        "href": "https://hostname/orgs/5dfcf075-c905-401e-9119-7c5331410dec",
        "type": "org",
        "sourcedId": "5dfcf075-c905-401e-9119-7c5331410dec"
      },
      {
        "href": "https://hostname/orgs/71eeebef-54a9-456a-9a7a-d71af5eaff97",
        "type": "org",
        "sourcedId": "71eeebef-54a9-456a-9a7a-d71af5eaff97"
      }
    ],
    "password": "98654"
  }
}

7.3. JSON format of a Updated type of Event data

Updated type of Event data object contains changes JSON section

{
  "sourcedId": "c949f252-13e2-4507-a9de-cab901d0065e",
  "eventType": "Student.Updated",
  "timestamp": "2020-01-13T12:38:13.023Z",
  "object": {
    "sourcedId": "885de493-5ae8-4688-858d-db66b5b277d1",
    "status": "active",
    "dateLastModified": "2020-01-13T12:38:13.023Z",
    "metadata": {
      "gg4l.primaryGrade": "06",
      "metadata.pnpfileurl": "facebook.com",
      "gg4l.primary_school": "5dfcf075-c905-401e-9119-7c5331410dec",
      "gg4l.preferred_contact_method": "email"
    },
    "username": "54021",
    "userIds": [
      {
        "type": "ORid",
        "identifier": "98124"
      },
      {
        "type": "LDAPid",
        "identifier": "14785236"
      },
      {
        "type": "sftp_id",
        "identifier": "student_04"
      },
      {
        "type": "statID",
        "identifier": "student_04"
      }
    ],
    "enabledUser": "false",
    "givenName": "Clark45",
    "familyName": "Kent43",
    "middleName": "F4",
    "role": "student",
    "identifier": "11242385",
    "email": "claek.kent44@tesmail.com",
    "sms": "12345678975",
    "phone": "8521747994564",
    "agents": [
      {
        "href": "https://hostname/datahub/services/ims/oneroster/v1p1/users/51b0ef66-8f58-4e12-9c6c-9dd344962441",
        "type": "user",
        "sourcedId": "51b0ef66-8f58-4e12-9c6c-9dd344962441"
      }
    ],
    "orgs": [
      {
        "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/5dfcf075-c905-401e-9119-7c5331410dec",
        "type": "org",
        "sourcedId": "5dfcf075-c905-401e-9119-7c5331410dec"
      },
      {
        "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/ca8614fa-6dd2-465f-b817-ad78c9194755",
        "type": "org",
        "sourcedId": "ca8614fa-6dd2-465f-b817-ad78c9194755"
      }
    ],
    "grades": [
      "06"
    ],
    "password": "24547687"
  },
  "changes": {
    "username": "000054021",
    "givenName": "Clark4",
    "familyName": "Kent4"
  }
}

7.4. JSON format of a Deleted type of Event data

{
  "sourcedId": "4262f51a-9765-468b-b991-d0fe15dfc3cd",
  "eventType": "Course.Deleted",
  "timestamp": "2020-01-13T16:07:03.577Z",
  "object": {
    "sourcedId": "7dfdeba7-d75a-4361-b5d1-19184a40d6d2",
    "status": "active",
    "dateLastModified": "2020-01-09T13:56:06.922Z",
    "metadata": {
      "metadata.duration": "two weeks"
    },
    "title": "WORLD MATH",
    "schoolYear": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/academicSessions/ec08a5ae-8b32-47a6-b48a-af3000e2475c",
      "type": "academicSession",
      "sourcedId": "ec08a5ae-8b32-47a6-b48a-af3000e2475c"
    },
    "courseCode": "01012",
    "grades": [
      "04",
      "03"
    ],
    "subjects": [
      "Technology"
    ],
    "org": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/8c9693ea-c15c-45b4-905c-d44d0e5bb53f",
      "type": "org",
      "sourcedId": "8c9693ea-c15c-45b4-905c-d44d0e5bb53f"
    },
    "subjectCodes": [
      "03210"
    ]
  }
}

7.5. JSON format of an Enrollment Event data

This type of Event gets generated when:

a user gets enrolled/unenrolled into/from a class
there are changes (like start/end date) to user’s enrollment details
a class, that a user is enrolled into, gets created or deleted

{
  "sourcedId": "1fcb34db-9d46-4595-a17a-6b86ee56ed4b",
  "eventType": "User.Enrolled",
  "timestamp": "2020-01-13T15:31:19.380Z",
  "object": {
    "sourcedId": "56c70491-8962-4bea-8f71-ade2c4f98c79",
    "status": "active",
    "dateLastModified": "2020-01-13T15:31:19.380Z",
    "role": "teacher",
    "primary": "false",
    "user": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/users/68dffad5-a464-4d47-a00f-b4dbd92ba07d",
      "type": "user",
      "sourcedId": "68dffad5-a464-4d47-a00f-b4dbd92ba07d"
    },
    "class": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/classes/b0d94f63-419c-41fc-affd-ec66ea8f1458",
      "type": "class",
      "sourcedId": "b0d94f63-419c-41fc-affd-ec66ea8f1458"
    },
    "school": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/5dfcf075-c905-401e-9119-7c5331410dec",
      "type": "org",
      "sourcedId": "5dfcf075-c905-401e-9119-7c5331410dec"
    },
    "beginDate": "2018-06-06",
    "endDate": "2020-12-07"
  }
}