OneRoster API Documentation (OAuth 2)

Classic View: System Administration > Learning Interoperability > select an application > select a OneRoster connection that uses OAuth 2 > Edit > Troubleshooting Documentation > OneRoster API Documentation

Search Terms: Digital Learning (select an application > select a OneRoster connection that uses OAuth 2 > Edit > Troubleshooting Documentation > OneRoster API Documentation)

The OneRoster API Documentation allows users to explore the data their district shares with the OneRoster API for connections that use OAuth 2. The data shown in this API documentation is what your Campus site makes available through OneRoster connections; vendors may not use all data made available through the API.

This tool is an implementation of Swagger, an industry-standard API documentation tool. Note: Connections using OAuth 1 are documented via the REST Documentation Client.

In most instances, Campus recommends only using the GET option, which allows you to view data and not modify it. The POST, PUT, and DELETE buttons of this tool allow a user to insert and delete records in Campus. Campus recommends not using the POST, PUT, and DELETE methods in your Production instance of Campus.

Accessing API Documentation

  1. From the Digital Learning Applications Configuration (formerly Learning Interoperability) tool, select an application that supports a OneRoster connection that uses OAuth 2. See the Configuring OneRoster Connections article for more information about setting up connections. 
  2. Identify which connection uses OAuth Version 2 and click Edit.
  3. In the Troubleshooting Documentation section, click the link for OneRoster API Documentation.

Screenshot of the OneRoster connections for a vendor with the OAuth version and edit button highlighted. For a connection that uses OAuth 2, click Edit and then click the
OneRoster API Documentation link. 
 

The API Documentation has three sections: 

  • The information at the top of the screen (the URL, the Servers dropdown list, and the Authorize button) are populated by default.
  • Next, API endpoints are grouped by the type of data they contain, such as AcademicSessionsManagement, ClassesManagement, etc. The endpoints in these groups represent the data that is available to vendors and allow you to mimic the full range of what a OneRoster Digital Learning Partner can do via the API.
  • Below the endpoints are the Schemas. This section can largely be ignored The schemas show in general terms the contents and order of a specific record type. Although these schemas can be expanded and viewed with the > button, these same schemas are also built into each Management section where they can be viewed with more context. 

Endpoint Management

Methods

The GET, POST, PUT, and DELETE options for endpoints allow you to send a sync request to your districts instance of the OneRoster API that mimic the requests that vendors send. Doing so lets you observe your Campus site's response and confirm that your site is making records available to your vendor via the API. 

Each endpoint has a method that describes what the endpoint does: 

  • GET: Sends a request to your Campus site to view the record(s) your site makes available through that API endpoint. This method is the recommended use of this Documentation tool. 
  • POST, PUT: Insert or update a record in your Campus site via the API. Not recommended for Production instances of Campus.
  • DELETE: Deletes a record in your Campus site via the API. Not recommended for Production instances of Campus.

Campus recommends only using the GET method in your Production instance to avoid modifying data.

OneRoster URLs

Screenshot of an example of a OneRoster URL with numbers indicating each of the sections, as described below.  Example of a OneRoster URL 

  1. All OneRoster endpoints begin the same with /api/oneroster/v1p2/{appName}/ims/oneroster.
  2. 'rostering' or 'gradebook,' indicates the type of record. Connections may have roster sync and/or grade book sync enabled on the configuration screen. 
  3. 'v1p2' indicates that you're using the 1.2 version of the API. 
  4. The name of the endpoint, such as 'academicSessions,' 'classes,' or 'orgs.'
  5. {SourcedId}, which are unique identifiers for records; if an endpoint specifies a sourcedId, it returns data specific to that entity, such as a class, school, or student.
  6. Following the URL is a simplified description of what that endpoint returns, such as getStudentsForClass.

For example, the endpoint shown above returns data for all students in a specific class. The class is specified by its sourcedId. 

Types of Queries

There are 3 types of queries, indicated by the format of the URL: 

  • getAll (...v1p2/endpoint name): Returns all records for the given endpoint.
    • For example, '...v1p2/classes' returns all class records available in the API.
  • get (...v1p2/endpoint name/{sourcedId}: Returns the specific record identified by the sourcedId.
    • For example, '...v1p2/demographics/{sourcedId}' returns the demographics record for the person identified by the sourcedId.
  • get...For (...v1p2/endpoint name/{sourceId}/endpoint name: Returns associated records for a specific record identified by the sourcedId. This is called a 'helper endpoint.'
    • For example, '....v1p2/schools/{schoolSourcedId}/classes' returns all classes for a specific school identified by the sourcedId.

Viewing Records

This API Documentation does not provide access to lineItem, Results, Program, or Assessment endpoints. A vendor's key and secret are required to interact with that data.

All Records and Total Counts

  1. In the endpoint group, such as classes or schools, find the getAllEndpointName URL and click GET to expand the endpoint.
  2. Click Try it out
  3. In the Parameters section, enter a limit for the number of records to return. If no limit is entered, the first 100 records report. See the Parameters section following for more options.
  4. Enter the appName, which displays at the end of your URL, as shown in this image:
    Screenshot of the documentation tool highlighting where the app name displays at the end of the URL. 
  5. Click Execute. This option only displays if you've clicked Try it out.

A Specific Record

  1. In the endpoint group, such classes or schools, find the getEndpointName URL and click GET to expand the endpoint.
  2. Click Try it out
  3. In the Parameters section, enter the sourcedId, which is the unique identifier of the record you're looking up based on the instructions provided above the field. See the OneRoster Data Models article for more information about sourcedIds.  
  4. Enter the appName, which displays at the end of your URL, as shown in this image:
    Screenshot of the documentation tool highlighting where the app name displays at the end of the URL. 
  5. Click Execute. This option only displays if you've clicked Try it out.


The response displays under Server Response in JSON format. Data is organized by a hierarchy of tags, starting with the object, embedded elements and values, and followed by any linked objects and their values.

See the Accessing Specific Data section following for specific examples of using the API Documentation to query OneRoster records.

Parameters

Expand below to view descriptions and examples of available parameters. 

Click here to expand...

The following parameters display for all getAll____ and get____For____ endpoints

ParameterDescription & NotesExample
filterOnly returns records that meet the entered criteria. 
  • Filters must follow the folloing format: fieldName='value'
  • The value is always surrounded by single quotes (').
  • = indicates equals and returns exact matches
  • ~ indicates contains and can be used instead of = to do a partial search.
  • The field name is case sensitive; the value is not case sensitive.
  • Multiple filters can be combined using AND or OR.
givenName='John' AND familyName~'Smi'
sortOrganizes results by the entered field name. 
  • The return, the field name used must occur within the results. If the field name is not valid, the sort parameter is ignored.
  • Field name is case sensitive.
familyName
orderByCan be used in conjunction with sort. Indicate if results should be in ascending (asc) or descending (desc) order. If blank, results usually sorted in ascending order. 
  • Not required if a sort value is entered.
  • This paramter does nothing on its own and is ignored if a sort value is not entered.
  • Only valid options are asc and desc.
desc
limitDetermines how many records are returned. 
  • Do not include a comma if entering a limit above 3 digits.
  • If no limit is entered, the first 100 records are returned.
1000
(Returns 1000 records at a time)
offsetCan be used in conjunction with limit. If no offset is entered, results begin with the first record. If an offset is entered, results begin with the entered number. 
  • If no limit is entered, returns 100 records.
1000
(Returns records staritng at record 1000)
fieldsLimits results returned to only the specific fields entered. 
  • When left blank, all fields display.
  • To return multiple fields, separate field names with commas.
  • When listing multiple fields, order does not matter; results are returned as ordered in the specification.
username, givenName, familyName

The following parameters display for get____ endpoints. 

ParameterDescription & NotesExample
fieldsLimits results returned to only the specific fields entered. 
  • When left blank, all fields display.
  • To return multiple fields, separate field names with commas.
  • When listing multiple fields, order does not matter; results are returned as ordered in the specification.
username, givenName, familyName
sourcedIdLimits results returned to those matching the sourcedId entered, which is the unique identifier use for OneRoster records. Enter the sourcedId of a specific record.

See the notes in the API Documentation next to each sourcedId for a description of the value required. See the Data Models article for more information.
SourcedId varies by endpoint. See Accessing Specific Data for more information.

Interpreting Results

After executing a GET command, data displays in the Server Responses section. This section is different from the Responses section, which contains general examples and schema information and can be ignored. 

The most useful content is in the Response Body. Ignore the technical information provided in the Curl. The Request URL is the endpoint you selected appended with any parameters. The Code is the HTTP response code issued by the Campus site in response to the sync request. A 200-level code indicates a successful request; a 400 or 500-level code indicates an error. See the Common Errors section following for more information. 

Common Errors/Response Codes

Click here to expand...

The following is a list of common errors that could indicate improper use of the OneRoster API Documentation tool rather than an actual issue with the OneRoster API itself. 

When an error occurs, consult the Code and "imsx_description" returned to learn more about the error.

Screenshot of an example of a server response, highlighting the error code and descriptions that display.Reference the Code to learn more about the error. 

CodeDescription
200
201
Success
Your Campus site was able to load the requested data. This is not an error; it indicates a successful GET request. 
Receiving a 200 with an empty Response Body that only includes the name of the endpoint and an empty set of brackets [ ] indicates that the request was successful but there is not data to display. An empty Response Body could indicate that the API does not contain any values that fit the Filters entered in the request. 
401User not authorized
This error is most commonly received when your session has timed out due to inactivity. The OneRoster API Documentation does not automatically log you out when your session has timed out. However, once you are no longer logged in to Campus, requests cannot be made to the API. If you receive this error, close the API Documentation tab, reopen it via the Digital Learning Applications Configuration tool, and resubmit the request. 
404Unknown object HTTP 404 not found
This error indicates that the record(s) requested are not available via your Campus site's instance of the API. To troubleshoot: 
  • Verify that the sourcedId is correct.
  • Ensure that you've entered the correct sourcedId for the given endpoint. 
  • In Campus, verify that the record in question is within the Active Year and that it is not marked as External LMS Exclude. 
422Invalid data; offset is not a modulus of limit: Invalid parameter 'offset' value of '____'. 
Indicates an incorrect Offset parameter. To troubleshoot, verify that the Offset value entered is a multiple of the Limit value. For example, if the Limit is 500, the Offset cannot be a value such as 100 or 600. With a Limit of 500, valid Offsets include 0, 500, 1000, 1500, etc. 
422Invalid data: Pagination limit value must not be greater than 50000: Invalid parameter 'limit' value of '____'. 
In Parameters, the Limit must be less than 50,000. If you need to see records beyond the first 50,000, submit a request with a smaller Limit and a corresponding Offset, such as a Limit of 1000 and an Offset of 50,000. 
400invalid_filter_field
Indicates an incorrect Filterparameter. To troubleshoot:
  • Verify that the Filter entered is correct. This field is case sensitive. 
  • Ensure that the Filter is surrounded by single quotes ('). 
  • Verify that the Filter entered is a field within the queried endpoint. 
400invalid_selection_field
Indicates an incorrect Fields parameter. Ensure that the Field entered is correct. This field is case sensitive. 

Response Body

The Response Body displays the returned records in JSON format. See the OneRoster 1.1 Data Models article for guidance in understanding this JSON content and where the data can be found in the Campus UI and database.

If the request was not successful, an Error displays instead of the Response Body. See Common Errors above for more information. 

Response Headers - x-total-count

The most useful part of the Response Headers section is the x-total-count, which is the total number of records available in the API to request in this endpoint, given the Filters entered above.

Screenshot highlighting the x-total-count in the response header. The x-total-count displays in the Response Headers section. 

Accessing Specific Data

The following sections detail looking up specific data using the API Documentation. These are just a few examples; other endpoints work the same.

Users

The Users endpoint includes students, teachers, non-teacher staff, guardians, and relatives. 

User by SourcedId (Person GUID)

Follow the steps below to view data for a specific user, as identified by sourcedId.

In OneRoster 1.2, the sourcedId for a user is the Person GUID, not the Person ID with a leading letter indicating their role, as it is in OneRoster 1.1. 

The user's Person GUID is found in their Demographics or Summary record.

  1. Scroll to getUser (or getTeacher, or getStudent).
  2. Click GET and then Try it out
  3. In the sourcedId field, enter the Person GUID of the user. 
  4. Click Execute.

If the user is included in your instance of the OneRoster API, their details display in the Response Body. The Role attribute indicates whether the user is a student, teacher, etc.

User by Filter (such as Name, Email, Username, etc)

Follow the steps below to view data for a specific user, as identified by a detail about the user.

  1. Scroll to getUser (or getTeacher, or getStudent).
  2. Click GET and then Try it out
  3. Enter a value in the Filter field as described in the table below. For a partial search, use the ~ symbol; for exact search, use =. 
  4. Click Execute.

If the user is included in your instance of the OneRoster API, their details display in the Response Body. The Role attribute indicates whether the user is a student, teacher, etc.

Look up user by:FilterExample
First and last name (exact)givenName='FirstName' AND familyName='LastName'givenName='John' AND familyName='Smith'
First name only (partial)givenName~'FirstName'givenName~'Joh'
Last name only (partial)familyName~'LastName'familyName~'Smi'
Emailemail='Email'email='john.smith@exampleschool.edu'
Usernameusername='Username'username='john.smith'

Schools a User is Associated with

In Campus, a student is associated with a school through their Enrollments; teachers and staff are associated with a school via District Assignments. In OneRoster, this association between a User and a School is represented by an 'org' reference (School GUID) listed in that person's User record. Only students and staff are associated with schools.

Once you've looked up a user record, find the org in the roles section of the Response Body. This section includes the org sourcedId. which is a different value than the user's sourcedId.

Use the org sourcedId, which is the School GUID in Campus, to look up the name of the school. To do so, either create an Ad hoc Filter that includes sch.schoolGUID and sch.name fields, or use the sourcedId to look up the School via the API Documentation. 

See a different School GUID than you expected? 
For a student: View the student's Enrollment and verify that External LMS Exclude is not marked. Verify that External LMS Exclude is also not marked for the student's Grade Level, Calendar, and School.

For a staff member: Verify that the user has a District Assignment in the correct school, has start and end dates within the Active Year and the School Year, and has the correct Role(s) marked. For teachers, the Role is Teacher; for non-teachers, the Role is Program with no other roles marked. Verify that External LMS Exclude is not marked on the District Assignment, School, or District.

For a guardian/relative: Only student and teachers records are associated with schools. 

Classes

Classes in OneRoster correspond to Sections in Campus. 

Classes by SourcedId (Section ID)

Follow the steps below to view data for a specific class, as identified by sourcedId.

The SourcedId of a class is the Section ID, which displays at the top of the Section Information

  1. Scroll to getClass.
  2. Click GET and then Try it out
  3. In the sourcedId field, enter the Section ID of the class. 
  4. Click Execute.

If the class is included in your instance of the OneRoster API, its details display in the Response Body.

Classes by Filter (Course/Section Number, etc)

Follow the steps below to view data for a specific class, as identified by a detail about the class.

  1. Scroll to getAllClasses.
  2. Click GET and then Try it out
  3. Enter a value in the Filter field as described in the table below. 
  4. Click Execute.

If the class is included in your instance of the OneRoster API, its details display in the Response Body.

Look up Class byFilterExample
Course Number and/or Section Numbertitle~'CourseNumber_space_SectionNumber'title~'1001 3a'
Course Nametitle~'CourseName'title~'AP Chemistry'
Teacher Display NameclassCode~'TeacherDisplayName'classCode~'Smith, John'
Note: The Teacher Display Name in the API may not be formatted as Last Name, First Name, although that is the default. Match the format to whatever displays as the Teacher Display Name on the Section.

Student Schedule/Staff History

Enrollments in OneRoster correspond to section roster records for students and section staff history records for teachers in Campus. To query data related to what Campus calls Enrollments, student membership in a specific school, see the Schools a User is Associated with section above. 

The Enrollments endpoint does not report the names of users or classes. Additionally, the sourcedId for enrollments records is not visible in the Campus UI. Therefore, Campus recommends filtering this endpoint by Person GUID or Section ID to generate a set of data that is more easily understood. Suggestions for ways to use this endpoint are found in the next four sections. 

Confirm User Association with a Class

Follow the steps below to confirm that a specific student is rostered into a specific class, or that a specific teacher is assigned to teach a specific class.

To start, locate the user's Person GUID, in the Demographics or Summary tools for students or the Demographics tool for teachers. Also locate the Section ID of the class, which displays at the top of the Section Information

  1. Scroll to getAllEnrollments.
  2. Click GET and then Try it out
  3. In the Filter field, enter a filter as follows:
    userSourcedId='PersonGUID' AND classSourcedId='SectionID'
    For example: userSourcedId='0A987F90-B6F1-47C1-8967-1A8A1234D563' AND classSourcedId ='285487'
  4. Click Execute.

If the user indicated by the Person GUID is associated with the Class specified in your instance of the OneRoster API, details display in the Response Body. The Person ID and Section ID of the user and class are shown, as well as a status for the association. Status options are 'active' and 'tobedeleted', which returns for inactive associations. 

Classes in a Student's Schedule

Follow the steps below to view a list of classes for a specific student.

To start, locate the student's Person GUID in the Demographics or Summary tools.

  1. Scroll to getAllEnrollments.
  2. Click GET and then Try it out
  3. In the Filter field, enter a filter as follows:
    userSourcedId='PersonGUID' AND role='student'
    For example: userSourcedId='0A987F90-B6F1-47C1-8967-1A8A1234D563' AND role='student'
  4. Click Execute.

If the student's roster records are available in your instance of the OneRoster API, details display in the Response Body, including the Section IDs of the classes on the student's schedule.

Classes a Teacher Teaches

Follow the steps below to view a list of classes a teacher teaches. 

To start, locate the teacher's Person GUID in the Demographics tool. 

  1. Scroll to getAllEnrollments.
  2. Click GET and then Try it out
  3. In the Filter field, enter a filter as follows:
    userSourcedId='PersonGUID' AND role='teacher'
    For example: userSourcedId='0A987F90-B6F1-47C1-8967-1A8A1234D563' AND role='teacher'
  4. Click Execute

If the teacher's Staff History records linking them to classes are available in your instance of the OneRoster API, details display in the Response Body, including the Section IDs of classes for which the teacher has staff history records.

Users Associated with a Specific Class

Follow the steps below to view a list of all users associated with a specific class, including students who are rostered into the class and teachers who have a section staff history record for the class. Data returned includes the status of the user in the class - whether the student has dropped the class or starts in the future, or whether the teacher's staff history record has ended or not started. 

The getStudentsForClass and getTeachersForClass helper endpoints also return users for a class. These endpoints provide full user records, but do not include the status of the users' memberships.

To start, locate the Section ID for the class, which displays at the top of the Section Information

  1. Scroll to getAllEnrollments.
  2. Click GET and then Try it out
  3. In the Filter field, enter a filter as follows:
    classSourcedId='SectionID'
    For example: classSourcedId='285487'
    If desired, include AND status='active' to return only active memberships.
  4. Click Execute

If there are student and/or teacher records associated with this class in your instance of the OneRoster API, details display in the Response Body. The following fields may be helpful: 

  • Role: A role of 'teacher' indicates that the user is associated with the class via a staff history record, with a "primary: true/false" field to indicate whether the teacher is a Primary Teacher or a [secondary] Teacher. A role of 'student' indicates that the user is associated via a roster record.
  • Status: Dropped or ended records (with an End Date prior to today) return with a status of 'tobedeleted,' compared to a status of 'active.' A status of 'tobedeleted' indicates to the vendor system that they may display the record as inactive or purge it, depending on that vendor's process.
  • x-total-count: It may be helpful to reference the x-total-count in the Response Headers to verify that the number of records returned for students and teachers matches the expected count.

Orgs (Schools & Districts)

Orgs in OneRoster correspond to both Schools and Districts in Campus. 

Specific School by Name

Follow the steps below to view data for a specific school, as identified by School Name.

To start, locate the School's Name in School Information

  1. Scroll to getAllSchools or getAllOrgs
  2. Click GET and then Try it out
  3. In the Filter field, enter a filter as follows:
    name~'SchoolName'
    For example: name~'Plainview High School'
  4. Click Execute

If the school is included in your instance of the OneRoster API, its details display in the Response Body, including the name and State School Number of the school.

Specific School by SourcedId

Follow the steps below to view data for a specific school, as identified by sourcedId.

To start, locate the School GUID for the school. This value is not visible in the Campus UI. To determine the GUID, either create an Ad hoc Filter that includes sch.schoolGUID and sch.name fields, or find the GUID in a User record.

  1. Scroll to getSchool or getOrg.
  2. Click GET and then Try it out
  3. In the sourcedId field, enter the school's School GUID. 
  4. Click Execute.

If the school is included in your instance of the OneRoster API, details display in the Response Body, including the name and State School Number of the school.

All Orgs

Follow the steps below to view a list of all orgs (districts and schools). 

  1. Scroll to getAllSchool or getAllOrg.
  2. Click GET and then Try it out
  3. Click Execute.

If school and district records are available in your instance of the OneRoster API, details display in the Response Body, including Name, State Numbers, and sourcedIds for the district and schools. 

Terms

Terms, Grading Periods, and Academic Sessions in OneRoster all correspond to Terms in Campus.

Terms by SourcedId (Term ID)

Follow the steps below to view data for a specific term, as identified by sourcedId.

The SourcedId of a term is the Term ID, which does not display in the Campus UI. To determine the GUID, either create an Ad hoc Filter or find the GUID in a Class record. 

  1. Scroll to getTerm.
  2. Click GET and then Try it out
  3. In the sourcedId field, enter the Term ID of the term. 
  4. Click Execute.

If the term is availble in your instance of the OneRoster API, details display in the Response Body, including Name, Dates, and sourcedId.

Terms by Name

Follow the steps below to view data for a term as identified by Term Name. If you district reuses term names across calendars, querying by term Name may not be specific enough.

To start, locate the Name of the term in question in Terms.

  1. Scroll to getAllTerms or getAllGradingPeriods, or getAllAcademicSessions.
  2. Click GET and then Try it out
  3. In the Filter field, enter a filter as follows:
    title~'TermName'
    For example: title~'Q1'
  4. Click Execute

If the term is available in your instance of the OneRoster API, details display in the Response Body, including the Name, Dates, and sourcedId. If multiple terms share the same name, multiple records may return.