Pearson
Always Learning

This API allows you to retrieve, create, update, or delete a grade for a student and gradable item. Unlike it's course-level counterpart, this API is student-specific and respects the rules set up in LearningStudio including gradebook review dates and whether the grade is shared with the student. It also returns works with only one grade at a time, and a student can only view their own grades (they cannot make changes).



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

API Request

API Endpoints

HTTP Verbs and URIs

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

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 (Student GETs only)
    (OAuth 2 only)
{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

No query string parameters are supported.

Request Body

For GET and DELETE Requests

None

For POST Requests

{
  "grade":{
    "points":{earnedPoints},
    "letterGrade":"{letterGrade}",
    "comments":"{commentText}"
  }
}

For PUT Requests

{
  "grade":{
    "id":{gradeId}
    "points":{earnedPoints},
    "letterGrade":"{letterGrade}",
    "comments":"{commentText}"
  }
}

Property Descriptions

Name Description Valid Values
{gradeId} LearningStudio Grade ID. Required in PUT request bodies despite also being in the endpoint. Numeric ID issued by LearningStudio
{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

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.

If using a student's OAuth 2 Access Token and either the grade is not share with the student, or the gradebook review date is not yet passed, this API will return a status code of 403 - Forbidden.

Response Body

Format

{
  "grade":[{
    "id":{gradeId},
    "points":{earnedPoints},
    "letterGrade":"{letterGrade}",
    "comments":"{commentText}",
    "shareWithStudent":{shareWithStudentFlag},
    "updatedDate":"{updatedDate}",
    "gradedStudent":{
      "id":{userId},
      "links":[{
        "href":"http://api.learningstudio.com/users/{userId}",
        "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.

Example: Get My Grade for Gradebook Item

Request

Endpoint

GET /me/courses/123456/gradebookItems/a24e4de6-ABCD-efgh-1234-123456789000/grade

Response

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"
      }]
    }
  }
}

Example: Create User's Grade for Gradebook Item

Request

Endpoint

POST /users/999999/courses/123456/gradebookItems/a24e4de6-ABCD-efgh-1234-123456789000/grade

Body

{
  "grade":{
    "points":10.00,
    "letterGrade":"A",
    "comments":"test grade comment text",
  }
}

Response

HTTP Headers

Location: https://api.learningstudio.com/courses/123456/gradebookItems/a24e4de6-ABCD-efgh-1234-123456789000/grades/18415
2500 reads
Always Learning
Pearson