OneRoster API Conventions

TimeBack's rostering and applications APIs follow the 1EdTech OneRoster v1.1 specification. This reference documents the standard query parameters for filtering, pagination, sorting, and field selection.

Filtering

Filter results using the filter query parameter with OneRoster filter syntax.

Syntax

filter=<field><predicate><value>

Predicates

Logical Operators

Combine multiple conditions with AND or OR:

filter=familyName='Smith' AND givenName='John'
filter=status='active' OR status='pending'

Constraints:

• Maximum of 2 predicates per filter expression (per OneRoster v1.1 spec)
• You cannot mix AND and OR in a single filter expression

Examples

Look up a user by email:

const email = encodeURIComponent("email='student@school.edu'");
const response = await fetch(`https://platform.timeback.com/rostering/1.0/users?filter=${email}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});

Find active applications:

const filter = encodeURIComponent("status='active'");
const response = await fetch(`https://platform.timeback.com/applications/1.0?filter=${filter}`, {
  headers: { Authorization: `Bearer ${accessToken}` },
});

Pagination

Control result set size and offset using limit and offset parameters.

Example

Fetch the second page of 20 results:

const response = await fetch('https://platform.timeback.com/rostering/1.0/users?limit=20&offset=20', {
  headers: { Authorization: `Bearer ${accessToken}` },
});

Response Pagination Info

All paginated responses include pagination metadata:

{
  "users": [...],
  "offset": 20,
  "limit": 20,
  "total": 150
}

Sorting

Sort results using sort and orderBy parameters.

Example

Get users sorted by family name descending:

const response = await fetch('https://platform.timeback.com/rostering/1.0/users?sort=familyName&orderBy=DESC', {
  headers: { Authorization: `Bearer ${accessToken}` },
});

Field Selection

Request only specific fields using the fields parameter to reduce response size.

Nested Fields

For nested objects, use dot notation:

fields=sourcedId,name,userProfiles.profileId,userProfiles.profileType

Example

Get only user IDs and emails:

const response = await fetch(
  'https://platform.timeback.com/rostering/1.0/users?fields=sourcedId,email,familyName,givenName',
  { headers: { Authorization: `Bearer ${accessToken}` } },
);

Related Docs

Level 1: Student Onboarding

Use filtering to look up users by email for Caliper event attribution.

Level 4: Insights API

Use the Applications API to map applicationId values in insights to application names.

Authentication

Obtain OAuth credentials required for API access.