Pearson
Always Learning

This API allows you to retrieve the grades entered for a gradable item, and create, update, or delete grades for specific students. Unless filtered, the retrieval will return all students grades for an item (if they exist), regardless of the gradebook review dates (OAuth 2 Access Tokens for students cannot use this API).



Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols OAuth 1.0a, OAuth 2.0
Valid for Roles (OAuth 2): Professor, Teaching Assistant, Administrator

API Request

API Endpoints

HTTP Verbs and URIs

GET /courses/{courseId}/gradebook/gradebookItems/{gradebookItemGuid}/grades{.format}
GET /courses/{courseId}/gradebookItems/{gradebookItemGuid}/grades{.format}
  • Retrieve all grades entered for a gradable item.
  • These endpoints are synonymous.
GET /courses/{courseId}/gradebook/gradebookItems/{gradebookItemGuid}/grades/{gradeId}{.format}
GET /courses/{courseId}/gradebookItems/{gradebookItemGuid}/grades/{gradeId}{.format}
  • Retrieve a specific grade.
  • These endpoints are synonymous.
POST /courses/{courseId}/gradebook/gradebookItems/{gradebookItemGuid}/grades{.format}
POST /courses/{courseId}/gradebookItems/{gradebookItemGuid}/grades{.format}
  • Create a new grade for a student in a specific gradable item.
  • These endpoints are synonymous.
PUT /courses/{courseId}/gradebook/gradebookItems/{gradebookItemGuid}/grades/{gradeId}{.format}
PUT /courses/{courseId}/gradebookItems/{gradebookItemGuid}/grades/{gradeId}{.format}
  • Update an existing grade.
  • These endpoints are synonymous.
DELETE /courses/{courseId}/gradebook/gradebookItems/{gradebookItemGuid}/grades/{gradeId}{.format}
DELETE /courses/{courseId}/gradebookItems/{gradebookItemGuid}/grades/{gradeId}{.format}
  • Delete a grade.
  • These endpoints are synonymous.

Parameters

Parameter Description Valid Values
{courseId} LearningStudio Course ID or relevant course overload.
  • Numeric ID issued by LearningStudio
  • ccn={callNumber}
{gradableItemGuid} LearningStudio Gradable Item GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio. String GUID issued by LearningStudio
{gradeId} LearningStudio Grade ID. Numeric ID issued by LearningStudio
{.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 a student's user object for each grade item. This parameter opts to include the user detail with the results of this API. user or Blank
gradedStudent By default the API will return entered grades for all students in the course. Use this query string parameter to filter the list to specific students, using their user IDs. Include multiple IDs by separating them with commas. LearningStudio numeric User IDs, separated by commas or Blank

Request Body

For GET and DELETE Requests

None

For POST Requests

{
  "grade":{
    "points":{earnedPoints},
    "letterGrade":"{letterGrade}",
    "comments":"{commentText}",
    "shareWithStudent" : {shareWithStudentFlag},
    "gradedStudent":{
      "id":{userId}
    }
  }
}

For PUT Requests

{
  "grades":{
    "id":{gradeId},
    "points" : {earnedPoints},
    "letterGrade" : "{letterGrade}",
    "comments":"{commentText}",
    "shareWithStudent" : {shareWithStudentFlag},
    "updatedDate":"{updatedDate}",
    "gradedStudent":{
      "id":{userId}
    }
  }
}

Property Descriptions

Name Description Valid Values
{earnedPoints} Number of points the student earned on the item. Any Float/Double number
{letterGrade} Letter grade earned by student (for example, A, B+), must be set with the grade. LearningStudio does not automatically assign letter grades to point values. String of text, should be 1-2 characters (e.g., "A" and optionally "+" or "-")
{commentText} Any comments related to the letter grade that will be shared with the student. Any string of text
{userId} LearningStudio user ID. A user ID value is only returned if the student is still actively enrolled in the corresponding course. If the user has been dropped, no user ID will be displayed for the associated grade entry. Numeric ID issued by LearningStudio
{gradeId} LearningStudio Grade ID. Required in PUT request bodies despite also being in the endpoint. Numeric ID issued by LearningStudio
{shareWithStudentFlag} Designates whether to share the grade information with the student. If false, the grade will not be available to students in the User Interface or student-specific API calls.
  • true
  • false
{updatedDate} Date and time the grade was last updated. This parameter is optional, but allows you to set a specific timestamp if performing a sync some time after the grade was changed in a different system (i.e., an SIS).

API Response

Response HTTP Status Codes and Headers

This API returns the standard HTTP Status Codes used by the LearningStudio APIs. There are no special headers returned by the API.

When updating an item, the API will return a status code of 204 - No Content with no response body.

Note: When creating a grade, the API will return a Location header, providing the location of the new grade object. See this page for more about this header.

Response Body

Format

{
  "grades":[{
    "id":{gradeId},
    "points":{earnedPoints},
    "letterGrade":"{letterGrade}",
    "comments":"{commentText}",
    "shareWithStudent":{shareWithStudentFlag},
    "updatedDate":"{updatedDate}",
    "gradedStudent":{
      "id":{userId},
      "links":[{
        "href":"{userHref}",
        "rel":"self"
        }]
    }
  }]
}

Property Descriptions

Name Description
{gradeId} LearningStudio Grade ID.
{earnedPoints} Number of points the student earned on the item.
{letterGrade} Letter grade earned by student (for example, A, B+). This is entered by the teacher when the grade is created. LearningStudio does not automatically assign letter grades to point values.
{commentText} Any comments related to the letter grade to display to the student.
{shareWithStudentFlag} Boolean that designates whether to share the grade information with the student.
{updatedDate} Date time the grade was last updated.
{userId} LearningStudio User ID.
{userHref} Link to the user detail object for this student. You can also use the expand parameter to include that object here (see Query String Parameters, above).

Example: Get Grades for Gradebook Item

This example is using a Query String Parameter to filter the results to two specific students in the course.

Request

Endpoint

GET /courses/123456/gradebookItems/a24e4de6-ABCD-efgh-1234-123456789000/grades?gradedstudent=88888,77777

Response

Body

{
  "grades":[{
    "id":18287,
    "points":10.00,
    "letterGrade":"A+",
    "comments":"test grade comment text",
    "updatedDate":"2010-09-09T16:22:41Z",
    "gradedStudent":{
      "id":88888,
      "links":[{
        "href":"https://api.learningstudio.com/users/88888",
        "rel":"self"
      }]
    }
  },{
    "id":18288,
    "comments":"test grade comment text",
    "updatedDate":"2010-09-09T16:22:41Z",
    "gradedStudent":{
      "id":77777,
      "links":[{
        "href":"https://api.learningstudio.com/users/77777",
        "rel":"self"
      }]
    }
  }]
}

Example: Create a Grade

Request

Endpoint

POST /courses/123456/gradebookItems/a24e4de6-ABCD-efgh-1234-123456789000/grades

Body

{
  "grade":{
    "points":10.00,
    "letterGrade":"A",
    "comments":"test grade comment text",
    "shareWithStudent":true,
    "gradedStudent":{
      "id":999999
    }
  }
}

Response

HTTP Headers

Location: https://api.learningstudio.com/courses/123456/gradebookItems/a24e4de6-ABCD-efgh-1234-123456789000/grades/18318

Body

{
  "grade":{
    "id":18318,
    "points":10.00,
    "letterGrade":"A",
    "comments":"test grade comment text",
    "updatedDate":"2010-09-09T16:22:41Z",
    "gradedStudent":{
      "id":999999,
      "links":[{
        "href":"https://api.learningstudio.com/users/999999",
        "rel":"self"
      }]
    }
  }
}
3509 reads
Always Learning
Pearson