OneRoster Endpoints

Triand's OneRoster Rostering REST API is a read-only service that exchanges roster data (orgs, users, courses, classes, enrollments, demographics). All endpoints are GET; POST, PUT, PATCH, and DELETE return 400.

Base URLs

The version is selected by the OAuth2 scope prefix on the access token (v1p1 vs v1p2). The URL prefix must match the scope prefix; mixing them returns 400. See Sample District for token retrieval.

Endpoints

All paths are relative to the version prefix above. {sourcedId} is the GUID-like identifier returned by the API.

Query Parameters

All collection endpoints accept the parameters below. Unknown parameters return 400.

Organizations & Schools

Academic Sessions, Terms, Grading Periods

Courses

Classes

Users, Students, Teachers

Enrollments

Demographics

Response Format

Collection endpoints return a JSON object keyed by the plural resource name; single-item endpoints use the singular key. Collection responses include an X-Total-Count header.

// Collection
{ "users": [ { "sourcedId": "...", "givenName": "...", ... } ] }

// Single item
{ "user": { "sourcedId": "...", "givenName": "...", ... } }

Record Status & Soft Delete

Every resource (org, user, class, course, enrollment, academic session, demographic) carries a status field with one of two values:

• "active" — the record is current.
• "tobedeleted" — the record has been removed from the upstream SIS and is being torn down.

When an entity disappears from the source data on a nightly sync, its OneRoster record is flagged "tobedeleted" rather than removed immediately. It remains queryable in the API for roughly 7 days with that status, then is hard-deleted on a later nightly run. This window gives consuming systems a chance to detect the disappearance and reconcile their own data.

Vendors should treat "tobedeleted" as "remove on next sync." The dateLastModified on a flagged record is updated to the day it was marked, which is useful for delta-sync filters such as filter=dateLastModified>'2025-01-01'.

Errors

Errors return a JSON envelope with an statusInfoSet describing the failure. The same envelope is also used for non-fatal warnings (e.g., an unknown fields entry) alongside a 200.

{
  "statusInfoSet": {
    "imsx_codeMajor": "failure",
    "imsx_severity": "error",
    "imsx_codeMinor": "invalid_filter_field",
    "imsx_description": "unknown field 'foo' [GET /users?filter=foo='bar']"
  }
}

Scope-Gated Behavior

Some fields and roles are conditionally included based on the scopes granted on the access token:

• guardians.readonly — includes users with role guardian in /users responses.
• guardians-metadata.readonly — includes the metadata object on guardian users.
• students-metadata.readonly — includes the metadata object on student users.
• demographic-metadata.readonly — includes the metadata object on demographic records.
• orgs-metadata.readonly — includes the metadata object on org responses.

See Data Dictionary for the full list of metadata fields and the scope each one requires.