APIs
      Back to home
      1. Help Center
      2. Using School Passport
      3. 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

      /enrollments/{id}/events

      Retrieves events for a specific enrollment

      GET

      /resources/{id}/events

      Retrieves events for a specific resource

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