Grade

Grades are associated with an enrollment and an assignment.

Table of Contents

Grades are point values assigned to users for a specific assignment through enrollments.

Fields

Field Name Description Type Required
enrollment_id Enrollment ID

The ID of the enrollment for which you are assigning a grade

 integer yes
assignment_id Assignment ID

The ID of the assignment for which you are assigning a grade

 string yes
grade Grade

The grade you are assigning the enrollment/assignment combination. Assignments with an assigned grading scale can accept letter-grades as defined by the scale - these will be converted to numeric values upon save.

 integer or string yes
exception Exception

An exception represents an exception to the grade item associated with this grade. If exception > 0 then grade will be set to NULL. Right now the only exceptions that exist are 1 for ‘excused’ & 2 for ‘incomplete’.

 integer
comment Comment

A comment to associate with this grade

 string
timestamp Timestamp

The Unix timestamp the last time the grade was updated in any way, according to the server time

 integer
is_final Is Final

Whether or the grade object belongs to a midterm/final.

 integer {0,1}
type Type

This is the type of grade item this grade refers to

 string {assignment, discussion}
location API location

This points to an API endpoint where the specific content this grade refers to can be found. Important that now there are assignments and discussions, meaning endpoints are not the same.

 string

Operations

list

View a list of grades (paged). The following query strings can (optionally) be appended to the path to filter results:

  • assignment_id: filter grades for a given assignment
  • enrollment_id: filter grades for a given enrollment
  • timestamp: return only grades that have been changed since the given timestamp, according to the server time.

Retrieving this list without specifying the above parameters will return a paged list of all grades for all assignments and students in the course section.

Path

GET https://api.schoology.com/v1/sections/{section_id}/grades

Content

none
Return

A collection of grade objects, each one containing grade fields

JSON 
{
    "grades": {
        "grade": [
            {
                "enrollment_id": 44783151,
                "assignment_id": 5699937,
                "grade": 80,
                "exception": 0,
                "max_points": 100,
                "is_final": 0,
                "timestamp": 1389651403,
                "comment": "",
                "comment_status": null,
                "override": null,
                "calculated_grade": null,
                "pending": null,
                "type": "assignment",
                "location": "http:\/\/...\/5699937",
                "scale_id": 1,
                "scale_type": 0,
                "category_id": 4341
            }
        ]
    },
    "period": [
        {
            "period_id": "p13011",
            "period_title": "Never Ending Period",
            "weight": "100.00"
        }
    ],
    "final_grade": [
        {
            "enrollment_id": "44783151",
            "period": [
                {
                    "period_id": "p13011",
                    "grade": 80,
                    "comment": "",
                    "comment_status": null
                },
                {
                    "period_id": "other",
                    "grade": null,
                    "comment": "",
                    "comment_status": null
                },
                {
                    "period_id": "final",
                    "grade": 80,
                    "comment": "",
                    "comment_status": null
                }
            ],
            "scale_id": 0
        }
    ]
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
  <grades>
    <grade>
      <enrollment_id>44783151</enrollment_id>
      <assignment_id>5699937</assignment_id>
      <grade>80</grade>
      <exception>0</exception>
      <max_points>100</max_points>
      <is_final>0</is_final>
      <timestamp>1389651403</timestamp>
      <comment />
      <comment_status />
      <override />
      <calculated_grade />
      <pending />
      <type>assignment</type>
      <location>http://.../5699937</location>
      <scale_id>1</scale_id>
      <scale_type>0</scale_type>
      <category_id>4341</category_id>
    </grade>
  </grades>
  <period>
    <period_id>p13011</period_id>
    <period_title>Never Ending Period</period_title>
    <weight>100.00</weight>
  </period>
  <final_grade>
    <enrollment_id>44783151</enrollment_id>
    <period>
      <period_id>p13011</period_id>
      <grade>80</grade>
      <comment />
      <comment_status />
    </period>
    <period>
      <period_id>other</period_id>
      <grade />
      <comment />
      <comment_status />
    </period>
    <period>
      <period_id>final</period_id>
      <grade>80</grade>
      <comment />
      <comment_status />
    </period>
    <scale_id>0</scale_id>
  </final_grade>
</result>

list

View a list of grades (paged) for a given user. Append the following query strings to the path to filter results:

  • section_id: filter grades for a given course section. Required
  • timestamp: return only grades that have been changed since the given timestamp, according to the server time. Optional

Retrieving this list without specifying the section_id parameter returns a 403 Forbidden error.

Retrieving this list without specifying the timestamp parameter returns all grades for all assignments and course sections, and for the section indicated by the section_id parameter.

Path

GET https://api.schoology.com/v1/users/{user_id}/grades

Content

none
Return

A collection of grade objects, each one containing grade fields

JSON 
{
    "section": [
        {
            "section_id": "4318461",
            "period": [
                {
                    "period_id": "p13011",
                    "period_title": "Never Ending Period",
                    "assignment": [
                        {
                            "enrollment_id": 44783151,
                            "assignment_id": 5699937,
                            "grade": 80,
                            "exception": 0,
                            "max_points": 100,
                            "is_final": 0,
                            "timestamp": 1389651403,
                            "comment": "",
                            "comment_status": null,
                            "override": null,
                            "calculated_grade": null,
                            "pending": null,
                            "type": "assignment",
                            "location": "http:\/\/...\/5699937",
                            "scale_id": 1,
                            "scale_type": 0,
                            "category_id": 4341
                        }
                    ]
                }
            ],
            "final_grade": [
                {
                    "period_id": "p13011",
                    "grade": 80,
                    "weight": 100,
                    "comment": "",
                    "scale_id": 0,
                    "grading_category": [
                        {
                            "category_id": 3081,
                            "grade": null
                        },
                        {
                            "category_id": 4341,
                            "grade": 80
                        }
                    ],
                    "comment_status": null
                },
                {
                    "period_id": "final",
                    "grade": 80,
                    "comment": "",
                    "comment_status": null,
                    "scale_id": 0
                }
            ],
            "grading_category": [
                {
                    "id": 3081,
                    "title": "e.g. Homework"
                },
                {
                    "id": 4341,
                    "title": "xtra points"
                }
            ]
        }
    ],
    "links": {
        "self": "http:\/\/...\/v1\/users\/48289\/grades"
    }
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
  <section>
    <section_id>4318461</section_id>
    <period>
      <period_id>p13011</period_id>
      <period_title>Never Ending Period</period_title>
      <assignment>
        <enrollment_id>44783151</enrollment_id>
        <assignment_id>5699937</assignment_id>
        <grade>80</grade>
        <exception>0</exception>
        <max_points>100</max_points>
        <is_final>0</is_final>
        <timestamp>1389651403</timestamp>
        <comment />
        <comment_status />
        <override />
        <calculated_grade />
        <pending />
        <type>assignment</type>
        <location>http://.../5699937</location>
        <scale_id>1</scale_id>
        <scale_type>0</scale_type>
        <category_id>4341</category_id>
      </assignment>
    </period>
    <final_grade>
      <period_id>p13011</period_id>
      <grade>80</grade>
      <weight>100</weight>
      <comment />
      <scale_id>0</scale_id>
      <grading_category>
        <category_id>3081</category_id>
        <grade />
      </grading_category>
      <grading_category>
        <category_id>4341</category_id>
        <grade>80</grade>
      </grading_category>
      <comment_status />
    </final_grade>
    <final_grade>
      <period_id>final</period_id>
      <grade>80</grade>
      <comment />
      <comment_status />
      <scale_id>0</scale_id>
    </final_grade>
    <grading_category>
      <id>3081</id>
      <title>e.g. Homework</title>
    </grading_category>
    <grading_category>
      <id>4341</id>
      <title>xtra points</title>
    </grading_category>
  </section>
  <links>
    <self>http://.../v1/users/48289/grades</self>
  </links>
</result>

update

Set/modify grades

Path

PUT https://api.schoology.com/v1/sections/{section_id}/grades

Content

Objects containing grade fields

JSON 
{
    "grades": {
        "grade": [
            {
                "type": "assignment",
                "assignment_id": 5007606,
                "enrollment_id": "44783136",
                "grade": 99,
                "comment": "grade submmitted"
            },
            {
                "type": "assignment",
                "assignment_id": 5007606,
                "enrollment_id": "44783141",
                "grade": 76,
                "comment": "grade submmitted"
            }
        ]
    }
}
XML 
<body>
  <grades>
    <grade>
      <type>assignment</type>
      <assignment_id>5007606</assignment_id>
      <enrollment_id>44783136</enrollment_id>
      <grade>99</grade>
      <comment>grade submmitted</comment>
    </grade>
    <grade>
      <type>assignment</type>
      <assignment_id>5007606</assignment_id>
      <enrollment_id>44783141</enrollment_id>
      <grade>76</grade>
      <comment>grade submmitted</comment>
    </grade>
  </grades>
</body>
Return

none

update final comments

Set/modify comments for students for a grading period and the overall course

Path

PUT https://api.schoology.com/v1/sections/{section_id}/grades

Content

Objects containing final comments fields

FieldNameDescriptionTypeRequired
enrollment_idEnrollment IDThe ID of the enrollment for which you are assigning a gradeintegeryes
period_idPeriod IdWhich grading period to post the comment for (if “final” is passed in as period_id, comment will post to final grade for course)integer OR "final"yes
commentCommentA comment to associate with this gradestringyes
comment_statusComment StatusWhether the comment is visible to the student (default is 0){1,0}no
JSON 
{
  "final_comments": {
    "final_comment": [
      {
        "enrollment_id": "24152019",
        "period_id": "26127",
        "comment": "Great improvement from first semester!",
        "comment_status": "1"
      },
      {
        "enrollment_id": "24152019",
        "period_id": "final",
        "comment": "Overall tremendous improvement",
        "comment_status": "1"
      }
    ]
  }
}
XML 
<body>
  <final_comments>
    <final_comment>
      <enrollment_id>24152019</enrollment_id>
      <period_id>26127</period_id>
      <comment>Great improvement from first semester!</comment>
      <comment_status>1</comment_status>
    </final_comment>
    <final_comment>
      <enrollment_id>24152019t</enrollment_id>
      <period_id>final</period_id>
      <comment>Overall tremendous improvement</comment>
      <comment_status>1t</comment_status>
    </final_comment>
  </final_comments>
</body>
Return

none