GET v4/courses/:course_id/rosters - Rosters

The roster API allows you to retrieve student enrollment for an LMS course(s) for a particular school. This roster data can enable a school's bookstore to better manage the school's digital course materials program when the school is utilizing the VitalSource LTI tool to access their digital materials.

Verb/URI
Data Definitions
Request Headers
Response
- Response Body
Successful Response Code and Message
Error Codes

This endpoint returns the enrolled students for a specific course.

Verb/URI

GET https://launch.vitalsource.com/api/v4/courses/:course_id/rosters

Data Definitions

Name	Usage	Description	Data Type	Example	Required
page	URL param / Message body	page number of roster request, default to page 1	integer	/rosters?page=1	No
per_page	URL param / Message body	number of roster records returned per request, default is 100	integer 1-1000	/rosters?per_page=1000	No
created_from	URL param / Message body	returns roster records that have been created at or since this time	ISO-8601 date/time	/rosters?created_from=2019-06-07T20:25:22Z	No
created_until	URL param / Message body	returns roster records that have been created at or until this time	ISO-8601 date/time	/rosters?created_until=2019-06-11T20:25:22Z	No
updated_until	URL param / Message body	returns roster records that have been updated at or since this time	ISO-8601 date/time	/rosters?updated_from=2019-06-07T20:25:22Z	No
updated_from	URL param / Message body	returns roster records that have been updated at or until this time	ISO-8601 date/time	/rosters?_updateduntil=2019-06-11T20:25:22Z	No
id	Message body	VitalSource identifier for the course user	integer	12345678910	N/A
tenant_id	Message body	VitalSource identifier for the school	integer	12345678910	N/A
course_id	URL path / Message body	VitalSource identifier for the course	integer	12345678910	N/A
first_name	Message body	First name of the course user	string	John	N/A
last_name	Message body	Last name of the course user	string	Doe	N/A
bookshelf_email_address	Message body	Email address associated with the course user's Bookshelf account	string	doe.john@emaildomain.com	N/A
access_token	Message body	Bookshelf token used to perform transactions on behalf of user	string	e6d12345678daf3c8dba3260f	N/A
reference_id	Message body	Reference identifier passed to VitalSource from the LMS used to create the Bookshelf user	string	st23haz95536wr3mii4p	N/A
guid	Message body	Global User ID, produced on user creation by VitalSource	string	YDAASDFGHJKLNRHPJ3Q6	N/A
lms_api_id	Message body	Unique user identifier sourced from the LMS platform	string	s6nohm1bb47b9pzky4mi	N/A
lms_username	Message body	Unique username sourced from the LMS platform	string	jdoe11	N/A
lti_user_id	Message body	Unique user id sourced from the LTI payload	string	s6nohm1bb47b9pzky4mi	N/A
lms_email_address	Message body	User email address sourced from the LTI payload. This may be different than the bookshelf_email_address	string	john.doe@school.edu	N/A
sis_id	Message body	Unique SIS identifier sourced from the LMS	string	710901181	N/A
role	URL param / Message body	User's role within the course	string	learner	No
active	URL param / Message body	Used to indicate if a user's enrollment in the course is active or if the user has withdrawn from the course	Boolean	true	No
last_synced	Message body	Indicates the date of the last sync with course & user data	ISO-8601 date/time	2018-12-04T15:59:59Z	N/A
created_at	Message body	Indicates the date the roster record was created in the VitalSource system	ISO-8601 date/time	2018-12-04T15:59:59Z	N/A
updated_at	Message body	Indicates the date the roster record was last updated in the VitalSource system	ISO-8601 date/time	2018-12-04T15:59:59Z	N/A

Request Headers

X-VitalSource-API-Key: ABCDEFGHIJKLMNOP
Accept: application/json
Content-type: application/json

Response

Response Body

{
  "page": 1,
  "per_page": 100,
  "num_items": 2,
  "total_pages": 1,
  "users": [
    {
      "id": 5260876,
      "course_id": 93284,
      "tenant_id": 1023,
      "first_name": "Jayden",
      "last_name": "Flower",
      "bookshelf_email_address": "jflowers12@coolemail.com",
      "access_token": "df614f60-fbd0-0136-c4e8-4200c9800d01",
      "reference_id": "ea3a4840",
      "guid": "1847780880537580048",
      "lms_api_id": "123456",
      "lms_username": "jflower12",
      "lti_user_id": "asj1nabca0evxzei8dy2",
      "lms_email_address": "jflower12@school.edu",
      "sis_id": "715639852"
      "role": "learner",
      "active": true,
      "last_synced": "2018-12-04T15:59:59Z",
      "created_at": "2018-12-04T15:59:59Z",
      "updated_at": "2018-12-04T15:59:59Z"
    },
    {
      "id": 5260036,
      "course_id": 93284,
      "tenant_id": 1029,
      "first_name": "Kayden",
      "last_name": "Jameson",
      "bookshelf_email_address": "alskdji387523ijehfd89@placeholder.1029.edu",
      "access_token": "91a15620-fbd1-0136-c4e8-4200c9800d01",
      "reference_id": "989e4540",
      "guid": "876539435145749112",
      "lms_api_id": "123457",
      "lms_username": "kjameson9",
      "lti_user_id": "6p7npqsmkon3tj6ww2gc",
      "lms_email_address": "kjameson9@school.edu",
      "sis_id": "712548975"
      "role": "learner",
      "active": true,
      "last_synced": "2018-12-04T15:59:59Z",
      "created_at": "2018-12-04T15:59:59Z",
      "updated_at": "2018-12-04T15:59:59Z"
    }
  ]
}

Successful Response Message

HTTP: 200 OK

Error Codes

HTTP Status	Message	Notes
401	Unauthorized	The API key provided is not associated with any LTI integration
404	Not found	The request parameters provided do not correspond to any known data