Table of contents
TOC
Collapse the table of content
Expand the table of content
Last Updated: 7/21/2017

Schools REST API reference

Applies to: Office 365 Education

This documentation covers features that are currently in preview.

Office 365 Education APIs help extract data from your Office 365 tenant which has been synced to the cloud by Microsoft School Data Sync. These results provide information about schools, sections, teachers, students and rosters. The Schools REST API provides access to school entities in Office 365 for Education tenants.

The API relies on Microsoft Azure Active Directory and OAuth to authenticate application requests.

To access the Schools REST API from your application, you'll need to register it in Azure Active Directory. You also need to manage authentication tokens, as well as construct the correct URL and queries to meet your needs. The examples below can be used to assist in the construction of your queries.

All Schools REST API operations

Schools are represented as Administrative Units in Azure Active Directory. You can get the schools that are available in a tenant and also get the sections, students, and teachers that are part of each school entity.

Get schools | Get sections within a school | Get students within a school | Get teachers within a school

Testing the APIs

All the school Roster APIs can be tested in an EDU Tenant using Graph Explorer. Navigate to Graph Explorer, sign in with your O365 EDU tenant credentials, select 'beta' as the version and copy/paste the URLs and verify the response.

Use the Schools REST API

To interact with the Schools REST API, you send HTTP GET requests.

All Schools REST API requests use the following root URL:

https://graph.microsoft.com/beta/administrativeUnits

Schools are represented in Azure Active Directory as administrative units. Extension attributes on the administrative units add education-specific information.
For example, the extension_fe2174665583431c953114ff7268b7b3_Education_HighestGrade attribute contains the highest grade level within the school.

Note All requests are required to specify 'beta' in the URL.

School Attributes

The description of attributes that help in identifying the information about the School are at: School Attributes


Get schools

You can get all schools, get a single school by its id, or get a collection of schools that match a set of query filters.

Get all schools

Get all schools that exist in the Azure Active Directory tenant.

https://graph.microsoft.com/beta/administrativeUnits/?$filter=extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType%20eq%20'School'

Response type

A collection of school entities.


Get a school

Get a school by using the id.

GET https://graph.microsoft.com/beta/administrativeUnits/{id}
Required parameterTypeDescription
URL parameters
idstringThe ID of the school administrative unit in Azure Active Directory.

Response type

The requested school entity.


Get sections within a school

Sections are represented in Azure Active Directory as Unified Groups. Extension attributes on the unified groups add section specific information. For example, the extension_fe2174665583431c953114ff7268b7b3_Education_CourseName attribute contains the course name for the section.

You can get sections for a specific school by querying for groups based on their school id, using the extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType attribute and the extension_fe2174665583431c953114ff7268b7b3_Education_SyncSource_SchoolId attribute together in the query.

GET  https://graph.microsoft.com/beta/groups?$filter=extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType%20eq%20'Section'%20and%20extension_fe2174665583431c953114ff7268b7b3_Education_SyncSource_SchoolId%20eq%20'10002'
Required parameterTypeDescription
URL parameters
school_idstringThe ID of the school in the School Information System (SIS), output of get schools

Response type

A collection of section entities.


Get students within a school

Students are represented in Azure Active Directory as users. Extension attributes on the users add student specific information. For example, the extension_fe2174665583431c953114ff7268b7b3_Education_Grade attribute contains the student's grade level.

You can get students in a specific school, by getting the members of the school administrative unit and filtering out non-student users from the resulting collection within your application.

Get school members

GET https://graph.microsoft.com/beta/administrativeUnits/{id}/members
Required parameterTypeDescription
URL parameters
idstringThe ID of the school administrative unit in Azure Active Directory.

Response type

A collection of users.

Find students

A collection of users might contain students, teachers, and non-education users (for example, administrative staff). You can filter the collection down to students within your application. Look for the Education_ObjectType extension attribute to equal Student.

extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType == 'Student'
GET https://graph.microsoft.com/beta/administrativeUnits/<GUID_AAD_ID_OF_SCHOOL_AU>/members/$/microsoft.graph.user?$filter=extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType%20eq%20'Student'

Get teachers within a school

Teachers are represented in Azure Active Directory as users. Extension attributes on the users add teacher specific information. For example, the extension_fe2174665583431c953114ff7268b7b3_Education_TeacherNumber attribute contains the teacher's teacher number.

You can get teachers in a specific school by getting the members of the school administrative unit and filtering out non-teacher users from the resulting collection within your application.

Get school members

GET https://graph.microsoft.com/beta/administrativeUnits/{id}/members
Required parameterTypeDescription
URL parameters
idstringThe ID of the school administrative unit in Azure Active Directory.

Response type

A collection of users.

Find teachers

A collection of users might contain students, teachers, and non-education users (for example, administrative staff). You can filter the collection down to teachers within your application. Look for the Education_ObjectType extension attribute to equal Teacher.

extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType == 'Teacher'
GET https://graph.microsoft.com/beta/administrativeUnits/<GUID_AAD_ID_OF_SCHOOL_AU>/members/$/microsoft.graph.user?$filter=extension_fe2174665583431c953114ff7268b7b3_Education_ObjectType%20eq%20'Teacher'

Next steps

Some of the other Education related resources that you might be interested in

Whether you're ready to start building an app or just want to learn more, we've got you covered.

Or, learn more about using the Office 365 platform:

© 2017 Microsoft