Help Center

Using School Passport

APIs

OneRoster API

This article provides an overview of the OneRoster API schema.

In this article

Revisions

OAuth 2 authorization - “Client credentials” grant

API Overview

Organizations

Schools

AcademicSessions

Terms

Courses

Classes

Users

Demographics

Enrollments

Teachers

Students

GrandingPeriods

Categories

Results

LineItems

Typical request parameters

Structure of JSON response from API

Extensions

Users

Demographics

Revisions

Document Version	Change Description	Effective Date
1.4	Gragebook attributes (GrandingPeriods, Categories, Results, LineItems) supported	Jul 01, 2023
1.3	OneRoster API v1.0 is no longer supported	Jul 01, 2019
1.2	‘primaryGrade’ attribute for Users moved to ‘gg4l.primaryGrade’ metadata extension	Feb 27, 2019
1.1	'primarySchool' attribute added as extension to users for teacher and student roles	Mar 11, 2019
1.0	Initial release	Feb 15, 2019

OAuth 2 Authorization - “Client credentials” grant

Request:

The request for client credentials must contain WWW BASIC authorization with both the client_id and client secret key in the request header, such as: ‘Authorization’: ‘Basic {data}’, where data = Base64.encode(‘{client_id}:{client secret}’).

POST

datahub/oauth/token

Endpoint for authenticating 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's type. Always ‘bearer’
expires_in	Integer	Expiration time in seconds
scope	String	List of scopes that define data access level

API Overview

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

Organizations

GET	/orgs	Retrieves a list of organizations you have access to
GET	/orgs/{id}	Retrieves information of a specific organization

Schools

GET	/schools	Retrieves a list of schools you have access to
GET	/schools/{id}	Retrieves information of a specific schools

AcademicSessions

GET	/academicSessions	Retrieves a list of academicSessions you have access to
GET	/academicSessions/{id}	Retrieves information of a specific academicSessions

Terms

GET	/terms	Retrieves a list of terms you have access to
GET	/terms/{id}	Retrieves information of a specific terms

Courses

GET	/courses	Gets a list of courses you have access to
GET	/courses/{id}	Gets only a specific courses information
GET	/schools/{id}/courses	Retrieves courses for schools

Classes

GET	/classes	Gets a list of classes you have access to
GET	/classes/{id}	Gets only a specific classes information
GET	/schools/{id}/classes	Retrieves classes for schools
GET	/terms/{id}/classes	Retrieves classes for terms
GET	/courses/{id}/classes	Retrieves classes for a courses
GET	/students/{id}/classes	Retrieves classes for students
GET	/teachers/{id}/classes	Retrieves classes for teachers

Users

GET	/users	Retrieves a list of users you have access to
GET	/users/{id}	Retrieves information of specific users

Demographics

GET	/demographics	Retrieves a list of all user’s demographics you have access to
GET	/demographics/{id}	Retrieves information of a specific user’s demographics

Enrollments

GET	/enrollments	Gets a list of student’s enrollments you have access to
GET	/enrollments/{id}	Gets only a specific student’s enrollments information
GET	/schools/{id}/classes/{id}/enrollments	Retrieves enrollments for classes in schools
GET	/schools/{id}/enrollments	Retrieves enrollments for schools

Teachers

GET	/teachers	Gets a list of teachers you have access to
GET	/teachers/{id}	Gets only a specific teachers information
GET	/schools/{id}/classes/{id}/teachers	Retrieves teachers for classes in schools
GET	/schools/{id}/teachers	Retrieves teachers for schools
GET	/classes/{id}/teachers	Retrieves teachers for classes

Students

GET	/students	Gets a list of students you have access to
GET	/students/{id}	Gets only a specific students information
GET	/schools/{id}/classes/{id}/students	Retrieves students for classes in schools
GET	/schools/{id}/students	Retrieves students for schools
GET	/classes/{id}/students	Retrieves students for classes

GrandingPeriods

GET	/gradingPeriods	Gets a list of grading periods you have access to
GET	/gradingPeriods/{id}	Gets only a specific grading period

Results

GET	/results	Gets a list of results you have access to
GET	/classes/{id}/results	Gets results for a specific class
GET	/classes/{classId}/lineItems/{id}/results	Gets results for line items in classes
GET	/classes/{classId}/students/{id}/results	Gets results for students in classes
GET	/results/{id}	Gets a specific result
PUT	/results/{id}	Creates or updates a result
DELETE	/results/{id}	Deletes a specific result

LineItems

GET	/lineItems	Gets a list of line items you have access to
GET	/classes/{id}/lineItems	Get line items for a specific class
GET	/lineItems/{id}	Gets a specific line item
PUT	/lineItems/{id}	Creates or updates a line item
DELETE	/lineItems/{id}	Delete a specific result

Note: If Grade Sync is disabled, the gragebook attributes (GrandingPeriods, Categories, Results, LineItems) are unavailable

Typical request parameters

Parameter	Mode	Type	Description
access_token	Required	String	The access token obtained during authorization
id	Required	GUID	An ID of a requested entity
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)

For example:

Return the first 10 resources in a collection of students:
GET https://hostname/learningdata/v1/students?limit=10
Return the second 10 resources in a collection of students:
GET https://imsglobal.org/learningdata/v1/students?limit=10&offset=10

Structure of JSON response from API

With a single data entity:

{
  "entityname":{
        "sourcedId": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
        "attribute1": "value of attribute 1",
        "attribute2": "value of attribute 2",
        "attribute3": "value of attribute 3"
        "entityreferences":[
             {
                 "href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
                 "sourcedId": "<related entity sourcedId>",
                 "type": "<related entity type>"
             },
             …
             {
                 "href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
                 "sourcedId": "<related entity sourcedId>",
                 "type": "<related entity type>"
             }
        ]
    }
}

With multiple data entities:

{
  "entityname": [
    {
        "sourcedId": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
        "attribute1": "value of attribute 1",
        "attribute2": "value of attribute 2",
        "attribute3": "value of attribute 3"
        "entityreferences":[
             {
                 "href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
                 "sourcedId": "<related entity sourcedId>",
                 "type": "<related entity type>"
             },
             …
             {
                 "href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
                 "sourcedId": "<related entity sourcedId>",
                 "type": "<related entity type>"
             }
        ]

    },
    ….
    {
        "sourcedId": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
        "attribute1": "value of attribute 1",
        "attribute2": "value of attribute 2",
        "attribute3": "value of attribute 3"
        "entityreferences":[
             {
                 "href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
                 "sourcedId": "<related entity sourcedId>",
                 "type": "<related entity type>"
             },
             …
             {
                 "href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
                 "sourcedId": "<related entity sourcedId>",
                 "type": "<related entity type>"
             }
        ]
    }
  ]

Extensions

Metadata (Yes/No) - whether extension added as metadata

Users

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 grade that come from SIS (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)

GET	/categories	Gets a list of categories you have access to
GET	/categories/{id}	Gets only a specific category information
PUT	/categories/{id}	Creates or updates a category
DELETE	/categories/{id}	Deletes a specific category