Pearson
Always Learning

This API returns any start dates, end dates, and due dates that come after today for a user (gradebook review dates are not included). By default, no dates that come before today will be included, but this can be overridden using the since query string parameter (see below).

Note there are two versions of this API, differentiated by endpoint format. One returns only the dates specific to a course, the other returns all dates for a user across all their courses.

Different content items may have different contexts for using start and end dates. Some content items may be restricted so that student cannot access them outside the date range. Items without such restriction are mostly guidelines for when the material should be covered during the course. Refer to the Content Items API Access Restrictions detail for when and how to implement these restrictions, or use the expand query string parameter to include that information in these results (see below). Exams may only be accessible during the defined date range.

Note: By default, the date must be explicitly set in the course for it to appear here. Items that use the course start & end dates will not appear in this list unless you use the includeInherited query string parameter.

Note: Results are not paginated, but you can implement filters and pagination to reduce the size of the response payload.



Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols OAuth 1.0a, OAuth 2.0
Valid for Roles (OAuth 2): Professor, Teaching Assistant, Student, Administrator
Note: [Add any role-specific caveats here, like "Student roles can only do XXXX"]

API Request

API Endpoints

HTTP Verbs and URIs

GET /users/{userId}/courses/{courseId}/upcomingEvents{.format}
  • Retrieves the list of upcoming dates for items in the course.
GET /users/{userId}/upcomingEvents{.format}
  • Retrieves the list of upcoming dates the user from across all courses.

Parameters

Parameter Description Valid Values
{userId} LearningStudio User ID or relevant user overload.
  • Numeric ID issued by LearningStudio
  • loginid={clientString}|{username}
  • or replace /users/{userId} with /me (Administrator Roles cannot use this overload)
    (OAuth 2 only)
{courseId} LearningStudio Course ID or relevant course overload.
  • Numeric ID issued by LearningStudio
  • ccn={callNumber}
{.format} Desired format of response data. See Response Formats. .json , .xml , or Blank

Query String Parameters

Query Parameter Name Description Valid Values
expand By default the API will return a link to the full course schedule for an item. This parameter opts to include that detail, including the access rules (whether a student can access the content outside the dates), with the results of this API. schedule or Blank
offset Defines the number of records to skip, used when paginating the results. Must be combined with the limit parameter. Any integer.
limit Defines the number of records to return, used when paginating the results. Must be combined with the offset parameter. Any integer
types Limit the results to the type of content for which a date is assigned (e.g., you can limit the results to only exams). These are the same content types as used in the Content API. If not set, dates for all content of any type will be included. Multiple types can be specified, separated by commas. Example:
types=THREADS or types=TYPES,IQT
HTML
THREAD
IQT (Exams)
MANAGED_HTML
MANGED_OD (Office Docs)
MANGED_THREADS
MANGED_UPLOAD
MSOFFICEDOC
EXCEL
PPT
WORD
WEBUPLOAD
or Blank
since Only includes activity from after this date. If this date is before today then historical events will be included. A timestamp in this format::
MM/DD/YYYY
until Only includes activity up until this date. Unless since is used, only dates from today until this date are included. A timestamp in this format::
MM/DD/YYYY
sortby Determines whether to sort the events by a certain property. Sort is always in ascending order (A-Z or earliest dates first) when
type
title
category
includeInherited By default, only dates explicitly set in the course are included and dates inherited form the course start/end are not. Set this to true to include all dates for all items. Note this can result in a large number of results when not otherwise filtered, impacting performance. true or Blank
includeFutureTerms Defines whether to include events only for the current term or for the current term and all future terms in which the user is enrolled. Note this can result in a large number of results when not otherwise filtered, impacting performance.

Note: this parameter only applies to the endpoint that retrieves from all courses, i.e.,
/users/{userId}/upcomingEvents

true or Blank

Request Body

None

API Response

Response Headers

This API returns the standard HTTP Status Codes used by the LearningStudio APIs.

Additionally, the API will return an HTTP Header named Content-Range that provides the current pagination information and total number of results, in the following format:

Content-Range: items {beginNum}-{endNum}/{total}

Response Body

Format

{
  "upcomingEvents": [{
    "category": "{category}",
    "id": {courseItemId},
    "titleHeading":"{unitTitle}"
    "title": "{courseItemTitle}",
    "type": "{courseItemType}",
    "when": {
      "time": "{dateTime}"
    },
    "links": [
    {
      "href": "{itemHref}",
      "rel": "https://api.learningstudio.com/rel/item"
    },{
      "href": "{courseHref}",
      "rel": "https://api.learningstudio.com/rel/course"
    },{
      "href": "{scheduleHref}",
      "rel": "related",
      "title": "schedule"
    },{
	  "href": "{inheritedScheduleHref}",
	  "rel": "https://api.learningstudio.com/rel/inheritedSchedule"
	}]
  }]
}

Property Descriptions

Name Description
{category} The type of date. Values can be either start, end, or due.
{courseItemId} Content Item ID of the item this date is for.
{unitTitle} Title of course item's parent unit.
{courseItemTitle} Title of course item.
{courseItemType} Type of course item. Values are one of:
  • EXCEL
  • HTML
  • IQT
  • MANAGED_HTML
  • MANAGED_OD
  • MANAGED_THREADS
  • MANAGED_UPLOAD
  • MSOFFICEDOC
  • PPT
  • TEXT
  • THREAD
  • WEBUPLOAD
  • WORD
{dateTime} Date and time for the event. Format is ISO-8601, e.g. YYYY-MM-DDTHH:MM:SSZ.
{itemHref} A link to the content item detail. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the questions list. Learn more.
{courseHref} A link to the course information for the content item. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the questions list. Learn more.
{scheduleHref} A link to the full schedule and access control for the content item. You can also include this information in these results with the expand query string parameter (see above). Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the questions list. Learn more.
{inheritedScheduleHref} A link to the full schedule for the parent content item (i.e., a unit). This link only appears if the includeInherited query string parameter is used and this item's dates are inherited. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the questions list. Learn more.

Example: Get Upcoming Events with Expanded Schedule

Request

Endpoint

GET /users/12345/courses/888888/upcomingevents?expand=schedule

Response

HTTP Headers

Content-Range: items 1-25/25

Body

This example is truncated for brevity.

{
  "upcomingEvents": [{
    "category": "start",
    "id": 1008765432,
    "titleHeading":"Unit 3"
    "title": "Discussion",
    "type": "THREAD",
    "when": {
    "time": "2011-05-01T07:00:00Z"
    },
    "links": [
    {
      "href": "http://api.learningstudio.com/courses/2022660/items/200816147",
      "rel": "self"
    },{
      "href": "http://api.learningstudio.com/courses/2022660",
      "rel": "related"
    },{
      "schedule": {
      "accessSchedule": {
        "startDateTime": "2011-05-01T07:00:00Z",
        "endDateTime": "2015-01-01T07:00:00Z",
        "isInherited": true,
        "canAccessBeforeStartDateTime": true,
        "canAccessAfterEndDateTime": false
      }
      },
      "href": "http://api.learningstudio.com/courses/2022660/items/200816147/schedule",
      "rel": "related",
      "title": "schedule"
    }
    ]
  },
  { ... }
  ]
}
2920 reads
Always Learning
Pearson