Grade

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

Fields

FieldNameDescriptionTypeRequired
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 integer 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_id Enrollment ID The ID of the enrollment for which you are assigning a grade integer yes
period_id Period Id Which 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
comment Comment A comment to associate with this grade string yes
comment_status Comment Status Whether 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