Loading...

OneRoster v1.1 API

Intellischool makes rostering data available via a OneRoster v1.1 RESTful model API. This document describes the endpoints available. Note that the use of this endpoint requires that the data owner has an Intellischool Data Ops licence.

Base URI

The OneRoster API can be accessed via any of the regional Intellischool API services, or via the global unified API service. The route prefix is always /ims/oneroster/v1p1.

For example, to access the OneRoster API via the global unified endpoint:
https://api.intellischool.net/ims/oneroster/v1p1/{endpoint}

Alternatively, to access the OneRoster API via the AU-NSW regional service:
https://api.nsw.intellischool.com.au/ims/oneroster/v1p1/{endpoint}

Or the SG regional service:
https://api.intellischool.sg/ims/oneroster/v1p1/{endpoint}

Required scopes

In order to query the Intellischool OneRoster API, your auth token must have at least one of the following scopes enabled.

  • Name
    https://purl.imsglobal.org/spec/or/v1p1/scope/roster-core.readonly
    Type
    Description

    Read-only access to academic sessions, class, course, enrolment, grading period, organisations, schools, students, teachers, and users endpoints.

  • Name
    https://purl.imsglobal.org/spec/or/v1p1/scope/roster.readonly
    Type
    Description

    Read-only access to all endpoints except demographics.

  • Name
    https://purl.imsglobal.org/spec/or/v1p1/scope/roster-demographics.readonly
    Type
    Description

    Read-only access to the demographics endpoints.

  • Name
    https://purl.imsglobal.org/spec/or/v1p1/scope/resource.readonly
    Type
    Description

    Read-only access to the resources endpoints.

  • Name
    https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.readonly
    Type
    Description

    Read-only access to the grade book categories, line items, and results endpoints.

  • Name
    https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.createput
    Type
    Description

    Create and/or update to grade book categories, line items, and results endpoints.

  • Name
    https://purl.imsglobal.org/spec/or/v1p1/scope/gradebook.delete
    Type
    Description

    Delete objects via the categories, line items, and results endpoints.

Pagination

The OneRoster standard mandates the support of pagination on all endpoints that return a collection. The Intellischool OneRoster API fully supports the pagination mechanism defined in the standard.

Pagination is controlled via two parameters that may be appended to the query string of GET requests.

If you supply a non-numeric value for these parameters the API will return a 400 Bad Request response.

  • Name
    limit
    Type
    number
    Description

    The maximum number of results to return. Default is 100. Requests for page sizes greater than 1000 will result in a 400 Bad Request response.

  • Name
    offset
    Type
    number
    Description

    The index of the first record to return, where 0 is the first record in the dataset. Default is 0.

Sorting

The OneRoster standard also mandates support for collections to be returned in a sorted order. The Intellischool OneRoster API fully supports the sorting mechanism defined in the standard.

Sorting is controlled via two two parameters that may be appended to the query string of GET requests.

  • Name
    data_field
    Type
    string
    Description

    The field by which the data should be sorted. The field must exist in the OneRoster specification for the object being requested.

  • Name
    orderBy
    Type
    enum["asc"|"desc"]
    Description

    The order in which to sort the data; either asc for ascending order, or desc for descending order.

Filtering

Filtering is also mandated by the OneRoster standard. The Intellischool OneRoster API fully supports data filtering as per the standard.

Filtering is controlled through the optional filter parameter that can be appended to the query string of GET requests. For more information on filter formations, please refer to Section 3.4.3 of the OneRoster v1.1 Final Specification.

  • Name
    filter
    Type
    string
    Description

    A valid filter string as defined by the OneRoster v1.1 specification.

Field selection

By default, all fields for the object requested will be returned by the API. The Intellischool OneRoster API supports specifying a subset of fields to return.

We recommend only returning the fields required for your application when making OneRoster API requests. This ensures that your request size is as small as possible, therefore making the response to your request faster.

Field selection requests can be made by appending the fields parameter to the query string of GET requests.

  • Name
    fields
    Type
    string[]
    Description

    A comma-delimited list of valid OneRoster field names to be returned.

GET /academicSessions/:id?

getAcademicSessions

Returns an academic session object if an ID is specified. Otherwise, returns a collection of all academic sessions.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the academic session to retrieve.

Request

GET
/academicSessions/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/academicSessions \ -H "Authorization: Bearer {token}"

Response

{"academicSessions":[{"sourcedId":"b8501981-e2f6-4a62-b630-a7da2543c6bc","status":"active","dateLastModified":"20230123T110723.3245Z","title":"Semester 1, 2023","startDate":"20230129","endDate":"20230628","type":"term","parent":{"href":"https://api.intellischool.net/ims/oneroster/v1p1/academicSessions/fdfd80be-1f35-4d09-88fb-6ddbe380278b","sourcedId":"fdfd80be-1f35-4d09-88fb-6ddbe380278b","type":"academicSession"},"children":[{"href":"https://api.intellischool.net/ims/oneroster/v1p1/academicSessions/77c940c5-ab1c-4afd-bfcf-99402eb0ff40","sourcedId":"77c940c5-ab1c-4afd-bfcf-99402eb0ff40","type":"gradingPeriod"}],"schoolYear":"2023"}]}
GET /classes/:id?

getClasses

Returns a class object if an ID is specified. Otherwise, returns a collection of all classes.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the class to retrieve.

Request

GET
/classes/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/classes \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /courses/:id/classes

getClassesForCourse

Returns a collection of the classes that are teaching the identified course.

Required attributes

  • Name
    id
    Type
    string

    The ID of the course for which to retrieve classes.

Request

GET
/courses/:id/classes
curl -G https://api.intellischool.net/ims/oneroster/v1p1/courses/{id}/classes \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:id/classes

getClassesForSchool

Returns a collection of the classes that are taught at a school.

Required attributes

  • Name
    id
    Type
    string

    The ID of the school for which to retrieve classes.

Request

GET
/schools/:id/classes
curl -G https://api.intellischool.net/ims/oneroster/v1p1/schools/{id}/classes \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /students/:id/classes

getClassesForStudent

Returns a collection of the classes that a student is enrolled in.

Required attributes

  • Name
    id
    Type
    string

    The ID of the student for which to retrieve classes.

Request

GET
/students/:id/classes
curl -G https://api.intellischool.net/ims/oneroster/v1p1/students/{id}/classes \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /teachers/:id/classes

getClassesForTeacher

Returns a collection of the classes that a teacher is enrolled in.

Required attributes

  • Name
    id
    Type
    string

    The ID of the teacher for which to retrieve classes.

Request

GET
/teachers/:id/classes
curl -G https://api.intellischool.net/ims/oneroster/v1p1/teachers/{id}/classes \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /terms/:id/classes

getClassesForTerm

Returns a collection of the classes that are being taught in the identified term.

Required attributes

  • Name
    id
    Type
    string

    The ID of the term for which to retrieve classes.

Request

GET
/terms/:id/classes
curl -G https://api.intellischool.net/ims/oneroster/v1p1/terms/{id}/classes \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /users/:id/classes

getClassesForUser

Returns a collection of the classes that a user is enrolled in.

Required attributes

  • Name
    id
    Type
    string

    The ID of the user for which to retrieve classes.

Request

GET
/users/:id/classes
curl -G https://api.intellischool.net/ims/oneroster/v1p1/users/{id}/classes \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /courses/:id?

getCourses

Returns a course object if an ID is specified. Otherwise, returns a collection of all courses.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the course to retrieve.

Request

GET
/courses/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/courses \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:id/courses

getCoursesForSchool

Returns a collection of the courses taught by the identified school.

This endpoint will return the same data as the courses endpoint unless your auth token has been issued by a district, diocese, MAT, or another enterprise-level account.

Required attributes

  • Name
    id
    Type
    string

    The ID of the school from which to retrieve courses.

Request

GET
/schools/:id/courses
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{id}/courses \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /demographics/:id?

getDemographics

Returns a demographic object if an ID is specified. Otherwise, returns a collection of all demographics.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the demographic to retrieve.

Request

GET
/demographics/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/demographics \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /enrollments/:id?

getEnrollments

Returns an enrolment object if an ID is specified. Otherwise, returns a collection of all enrolments. Note the US English spelling of this endpoint - "enrollments" - as per OneRoster spec.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the enrolment to retrieve.

Request

GET
/enrollments/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/enrollments \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:school_id/classes/:class_id/enrollments

getEnrollmentsForClassInSchool

Returns a collection of the enrolments for a class at a particular school. Note the US English spelling of this endpoint: "enrollments".

Required attributes

  • Name
    school_id
    Type
    string

    The ID of the school from which to retrieve the enrolment data.

  • Name
    class_id
    Type
    string

    The ID of the class that you wish to retrieve enrolments for.

Request

GET
/schools/:school_id/classes/:class_id/enrollments
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{school_id}/classes/{class_id}/enrollments \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:school_id/enrollments

getEnrollmentsForSchool

Returns a collection of the enrolments at a particular school. Note the US English spelling of this endpoint: "enrollments".

This endpoint will return the same data as the enrollments endpoint unless your auth token has been issued by a district, diocese, MAT, or another enterprise-level account.

Required attributes

  • Name
    school_id
    Type
    string

    The ID of the school from which to retrieve the enrolment data.

Request

GET
/schools/:school_id/enrollments
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{school_id}/enrollments \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /gradingPeriods/:id?

getGradingPeriods

Returns a grading period object if an ID is specified. Otherwise, returns a collection of all grading periods.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the grading period to retrieve.

Request

GET
/gradingPeriods/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/gradingPeriods \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /terms/:id/gradingPeriods

getGradingPeriodsForTerm

Returns a collection of the grading periods within the identified term.

Required attributes

  • Name
    id
    Type
    string

    The ID of the term for which to retrieve grading periods.

Request

GET
/terms/:id/gradingPeriods
curl -G https://api.intellischool.net/ims/oneroster/v1p1/terms/{id}/gradingPeriods \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /orgs/:id?

getOrgs

Returns an organisation object if an ID is specified. Otherwise, returns a collection of all accessible organisations.

In regions outside of North America, an "organisation" may represent a "school", and the schools endpoint may return campuses or sub-schools.

Additionally, depending on the data access scope of the token used to retrieve data, this endpoint will likely only return one organisation. Only tokens issued from a district, diocese, MAT or other enterprise-level account may have access to multiple organisations.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the organisation to retrieve.

Request

GET
/orgs/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/orgs \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:id?

getSchools

Returns a school object if an ID is specified. Otherwise, returns a collection of all accessible schools.

In regions outside of North America the output of this endpoint may vary depending on the configuration of the data owner. In Australia, many data owners opt for school objects to refer to a campus or sub-school within the parent organisation/school.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the school to retrieve.

Request

GET
/schools/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/schools \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /students/:id?

getStudents

Returns a student object if an ID is specified. Otherwise, returns a collection of all accessible students.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the student to retrieve.

Request

GET
/students/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/students \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /classes/:id/students

getStudentsForClass

Returns a collection of the students that are enrolled in the identified class.

Required attributes

  • Name
    id
    Type
    string

    The ID of the class for which to retrieve students.

Request

GET
/classes/:id/students
curl -G https://api.intellischool.net/ims/oneroster/v1p1/classes/{id}/students \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:school_id/classes/:class_id/students

getStudentsForClassInSchool

Returns a collection of the students enrolled in a class at a particular school.

Required attributes

  • Name
    school_id
    Type
    string

    The ID of the school from which to retrieve the enrolment data.

  • Name
    class_id
    Type
    string

    The ID of the class that you wish to retrieve enrolments for.

Request

GET
/schools/:school_id/classes/:class_id/students
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{school_id}/classes/{class_id}/students \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:school_id/students

getStudentsForSchool

Returns a collection of the students enrolled at a particular school.

This endpoint will return the same data as the students endpoint unless your auth token has been issued by a district, diocese, MAT, or another enterprise-level account.

Required attributes

  • Name
    school_id
    Type
    string

    The ID of the school from which to retrieve the student data.

Request

GET
/schools/:school_id/students
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{school_id}/students \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /teachers/:id?

getTeachers

Returns a teacher object if an ID is specified. Otherwise, returns a collection of all accessible teachers.

On the Intellischool data platform this endpoint will return all staff; not just teachers.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the teacher to retrieve.

Request

GET
/teachers/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/teachers \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /classes/:id/students

getTeachersForClass

Returns a collection of the teachers that are enrolled in the identified class.

Required attributes

  • Name
    id
    Type
    string

    The ID of the class for which to retrieve teachers.

Request

GET
/classes/:id/students
curl -G https://api.intellischool.net/ims/oneroster/v1p1/classes/{id}/teachers \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:school_id/classes/:class_id/teachers

getTeachersForClassInSchool

Returns a collection of the teachers for a class at a particular school.

Required attributes

  • Name
    school_id
    Type
    string

    The ID of the school from which to retrieve the enrolment data.

  • Name
    class_id
    Type
    string

    The ID of the class that you wish to retrieve enrolments for.

Request

GET
/schools/:school_id/classes/:class_id/teachers
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{school_id}/classes/{class_id}/teachers \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:school_id/teachers

getTeachersForSchool

Returns a collection of the staff working at a particular school.

On the Intellischool data platform this endpoint will return all staff; not just teachers.

This endpoint will return the same data as the teachers endpoint unless your auth token has been issued by a district, diocese, MAT, or another enterprise-level account.

Required attributes

  • Name
    school_id
    Type
    string

    The ID of the school from which to retrieve the student data.

Request

GET
/schools/:school_id/teachers
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{school_id}/students \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /terms/:id?

getTerms

Returns a term object if an ID is specified. Otherwise, returns a collection of all accessible terms.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the term to retrieve.

Request

GET
/terms/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/terms \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /schools/:school_id/terms

getTermsForSchool

Returns a collection of the terms scheduled for a particular school.

This endpoint will return the same data as the terms endpoint unless your auth token has been issued by a district, diocese, MAT, or another enterprise-level account.

Required attributes

  • Name
    school_id
    Type
    string

    The ID of the school from which to retrieve the term data.

Request

GET
/schools/:school_id/terms
curl -X GET https://api.intellischool.net/ims/oneroster/v1p1/schools/{school_id}/terms \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }
GET /users/:id?

getUsers

Returns a user object if an ID is specified. Otherwise, returns a collection of all accessible users.

Optional attributes

  • Name
    id
    Type
    string

    The ID of the user to retrieve.

Request

GET
/users/:id?
curl -G https://api.intellischool.net/ims/oneroster/v1p1/users \ -H "Authorization: Bearer {token}"

Response

{ "attribute_name": "attribute_value" }