Assignment

Assignments are containers for coursework and test/quizzes. Every assignment has an entry in the gradebook.

Fields

FieldNameDescriptionTypeRequired
title Title The assignment title string yes
description Description The assignment description integer
due Due Date When the assignment is due datetime
(YYYY-MM-DD HH:MM:SS)
grading_scale Grading Scale The ID of the grading scale for this assignment. For no grading scale, use "0". Course grading scales can be found on the course Grade Setup page. integer default: 0
grading_period Grading Period The grading period ID to which this assignment belongs. For "Other", use "0". integer default: 0
grading_category Grading Category The grading category ID to which this assignment belongs integer default: 0
max_points Maximum Points The maximum number of points for this assignment (excl. extra credit) float default: 100
factor Factor The relative weight of this assignment float default: 1.0
is_final Is a Final Mark this assignment as a midterm or final {0,1} default: 0
show_comments Show Comments Show grade comments to students {0,1} default: 0
grade_stats Assignment Grade Statistics Visibility
  • 0: Hide statistics
  • 1: Show statistics without bell curve
{0,1} default: 0
allow_dropbox Enable Dropbox Allow students to post assignment submissions to a dropbox. {0,1} default: 1
allow_discussion Enable Assignment Discussion Enable the assignment profile discussion board {0,1} default: 1
published Assignment is published Whether or not the assignment is published {0,1} default: 1
type The type of Grade Item Distinguishes different types of grade items (grade items being a broad term for anything that can have a grade). {assignment, discussion, assessment}
grade_item_id ID of the node that can be graded If this is of type assignment, this ID will point to the assignment object id attribute. If this is of type discussion, this ID will point to the discussion object ID. integer
dropbox_submissions Number of dropbox submissions This field is only available to teachers and will only be returned if the ?with_dropbox_stats=TRUE argument is given. This is a snapshot of the number of submissions in this assignments dropbox integer
dropbox_last_submission Time of the last dropbox submission This field is only available to teachers and will only be returned if the ?with_dropbox_stats=TRUE argument is given. This is a timestamp representing when the last dropbox revision was submitted. integer
show_rubric Display rubric to students This field is true when the assignment is using a rubric and the teacher has enabled the option for students to see the rubric. bool
assignees Individually Assigned enrollments This field shows which enrollees are assigned a particular assignment. This field can be used in a POST or PUT operation. If an empty array is sent in, all assignees will be removed from the assignment array of enrollment ids
grading_group_ids Grading Group Ids This field shows what grading groups are assigned a particular assignment. This field can be used in a POST or PUT operation. If an empty array is sent in, all grading groups will be removed from the assignment array of grading group ids

Operations

create

Create an assignment

Path

POST https://api.schoology.com/v1/sections/{section_id}/assignments

Content

An object containing assignment fields

JSON 
{
    "title": "The assignment title",
    "description": "The assignment description",
    "due": "2014-09-25 11:30:00",
    "type": "assignment",
    "assignees":[ 12345, 4567],
    "grading_group_ids": [534]
}
XML 
<body>
  <title>The assignment title</title>
  <description>The assignment description</description>
  <due>2014-09-25 11:30:00</due>
  <type>assignment</type>
  <assignees>12345</assignees>
  <assignees>12345</assignees>
  <grading_group_ids>534</grading_group_ids>
</body>
Return

An object containing assignment fields

JSON 
{
    "id": 5699937,
    "title": "this is a test assignment",
    "description": "extra credit assignment",
    "due": "2014-09-25 11:30:00",
    "grading_scale": "0",
    "grading_period": "13011",
    "grading_category": "0",
    "max_points": "100",
    "factor": "1",
    "is_final": "0",
    "show_comments": "0",
    "grade_stats": "0",
    "allow_dropbox": "1",
    "allow_discussion": "1",
    "published": 1,
    "type": "assignment",
    "grade_item_id": 5699937,
    "available": 1,
    "completed": 0,
    "dropbox_locked": 0,
    "grading_scale_type": 0,
    "show_rubric": false,
    "num_assignees": 4,
    "assignees": [
        12345,
        4567,
        888,
        999
    ],
    "grading_group_ids": [
        534
    ],
    "links": {
        "self": "http:\/\/...\/assignments\/5699937"
    }
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <id>5699937</id>
    <title>this is a test assignment</title>
    <description>extra credit assignment</description>
    <due>2014-09-25 11:30:00</due>
    <grading_scale>0</grading_scale>
    <grading_period>13011</grading_period>
    <grading_category>0</grading_category>
    <max_points>100</max_points>
    <factor>1</factor>
    <is_final>0</is_final>
    <show_comments>0</show_comments>
    <grade_stats>0</grade_stats>
    <allow_dropbox>1</allow_dropbox>
    <allow_discussion>1</allow_discussion>
    <published>1</published>
    <type>assignment</type>
    <grade_item_id>5699937</grade_item_id>
    <available>1</available>
    <completed>0</completed>
    <dropbox_locked>0</dropbox_locked>
    <grading_scale_type>0</grading_scale_type>
    <show_rubric></show_rubric>
    <num_assignees>4</num_assignees>
    <assignees>12345</assignees>
    <assignees>4567</assignees>
    <assignees>888</assignees>
    <assignees>999</assignees>
    <grading_group_ids>534</grading_group_ids>
    <links>
        <self>http://.../assignments/5699937</self>
    </links>
</result>

list

View a list of assignments. Note that assignments are first ordered by assignment type (non-final and final), and then by due date. Also, the standard 'start' and 'limit' key pairs are applied to these types individually for each call. For example, if you append '&lmiit=2' to a call to this endpoint, you will get back 2 non-final assignments and 2 final assignments, ordered in the expected way. This endpoint only returns grade-items of type assignment. The following query strings can (optionally) be appended:

  • with_attachments: retrieve attachments of this piece of content.
  • with_tags: retrieve tags of this piece of content.
  • limit: Number of results.
Path

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

Content

none

Return

A collection of assignment objects, each one containing assignment fields

JSON 
{
    "assignment": [
        {
            "id": 5699937,
            "title": "this is a test assignment",
            "description": "extra credit assignment",
            "due": "2014-09-25 11:30:00",
            "grading_scale": "0",
            "grading_period": "13011",
            "grading_category": "0",
            "max_points": "100",
            "factor": "1",
            "is_final": "0",
            "show_comments": "0",
            "grade_stats": "0",
            "allow_dropbox": "1",
            "allow_discussion": "1",
            "published": 1,
            "type": "assignment",
            "grade_item_id": 5699937,
            "available": 1,
            "completed": 0,
            "dropbox_locked": 0,
            "grading_scale_type": 0,
            "show_rubric": false,
            "num_assignees": 4,
            "assignees": [
               12345,
               4567,
               888,
               999
           ],
           "grading_group_ids": [
              534
            ],
            "completion_status": "",
            "links": {
                "self": "http:\/\/...\/assignments\/5699937"
            }
        }
    ],
    "total": 1,
    "links": {
        "self": "http:\/\/...\/assignments?start=0&limit=20"
    }
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <assignment>
        <id>5699937</id>
        <title>this is a test assignment</title>
        <description>extra credit assignment</description>
        <due>2014-09-25 11:30:00</due>
        <grading_scale>0</grading_scale>
        <grading_period>13011</grading_period>
        <grading_category>0</grading_category>
        <max_points>100</max_points>
        <factor>1</factor>
        <is_final>0</is_final>
        <show_comments>0</show_comments>
        <grade_stats>0</grade_stats>
        <allow_dropbox>1</allow_dropbox>
        <allow_discussion>1</allow_discussion>
        <published>1</published>
        <type>assignment</type>
        <grade_item_id>5699937</grade_item_id>
        <available>1</available>
        <completed>0</completed>
        <dropbox_locked>0</dropbox_locked>
        <grading_scale_type>0</grading_scale_type>
        <show_rubric></show_rubric>
        <num_assignees>4</num_assignees>
        <assignees>12345</assignees>
        <assignees>4567</assignees>
        <assignees>888</assignees>
        <assignees>999</assignees>
        <grading_group_ids>534</grading_group_ids>
        <completion_status />
        <links>
            <self>http://.../assignments/5699937</self>
        </links>
    </assignment>
    <total>1</total>
    <links>
        <self>http://.../assignments?start=0&amp;limit=20</self>
    </links>
</result>

list

This endpoint returns any type of content that can be graded (e.g. assignment and discussions). The following query strings can (optionally) be appended:

  • with_attachments: retrieve attachments of this piece of content.
  • with_tags: retrieve tags of this piece of content.
Path

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

Content

none

Return

A collection of assignment objects, each one containing assignment fields

JSON 
{
    "assignment": [
        {
            "id": 5699937,
            "title": "this is a test assignment",
            "description": "extra credit assignment",
            "due": "2014-09-25 11:30:00",
            "grading_scale": "0",
            "grading_period": "13011",
            "grading_category": "0",
            "max_points": "100",
            "factor": "1",
            "is_final": "0",
            "show_comments": "0",
            "grade_stats": "0",
            "allow_dropbox": "1",
            "allow_discussion": "1",
            "published": 1,
            "type": "assignment",
            "grade_item_id": 5699937,
            "available": 1,
            "completed": 0,
            "dropbox_locked": 0,
            "grading_scale_type": 0,
            "show_rubric": false,
            "num_assignees": 0,
            "assignees": [

            ],
            "completion_status": "",
            "links": {
                "self": "http:\/\/...\/grade_items\/5699937"
            }
        }
    ],
    "total": 1,
    "links": {
        "self": "http:\/\/...\/grade-items?start=0&limit=20"
    }
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <assignment>
        <id>5699937</id>
        <title>this is a test assignment</title>
        <description>extra credit assignment</description>
        <due>2014-09-25 11:30:00</due>
        <grading_scale>0</grading_scale>
        <grading_period>13011</grading_period>
        <grading_category>0</grading_category>
        <max_points>100</max_points>
        <factor>1</factor>
        <is_final>0</is_final>
        <show_comments>0</show_comments>
        <grade_stats>0</grade_stats>
        <allow_dropbox>1</allow_dropbox>
        <allow_discussion>1</allow_discussion>
        <published>1</published>
        <type>assignment</type>
        <grade_item_id>5699937</grade_item_id>
        <available>1</available>
        <completed>0</completed>
        <dropbox_locked>0</dropbox_locked>
        <grading_scale_type>0</grading_scale_type>
        <show_rubric></show_rubric>
        <num_assignees>0</num_assignees>
        <assignees />
        <completion_status />
        <links>
            <self>http://.../grade_items/5699937</self>
        </links>
    </assignment>
    <total>1</total>
    <links>
        <self>http://.../grade-items?start=0&amp;limit=20</self>
    </links>
</result>

view

View a specified assignment. The following query strings can (optionally) be appended:

  • with_attachments: retrieve attachments of this piece of content.
  • with_tags: retrieve tags of this piece of content.
Path

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

Content

none

Return

An object containing assignment fields

JSON 
{
    "id": 5699937,
    "title": "this is a test assignment",
    "description": "extra credit assignment",
    "due": "2014-09-25 11:30:00",
    "grading_scale": "0",
    "grading_period": "13011",
    "grading_category": "0",
    "max_points": "100",
    "factor": "1",
    "is_final": "0",
    "show_comments": "0",
    "grade_stats": "0",
    "allow_dropbox": "1",
    "allow_discussion": "1",
    "published": 1,
    "type": "assignment",
    "grade_item_id": 5699937,
    "available": 1,
    "completed": 0,
    "dropbox_locked": 0,
    "grading_scale_type": 0,
    "show_rubric": false,
    "num_assignees": 0,
    "assignees": [

    ],
    "completion_status": ""
}
XML 
<?xml version="1.0" encoding="utf-8" ?>
<result>
	<id>5699937</id>
	<title>this is a test assignment</title>
	<description>extra credit assignment</description>
	<due>2014-09-25 11:30:00</due>
	<grading_scale>0</grading_scale>
	<grading_period>13011</grading_period>
	<grading_category>0</grading_category>
	<max_points>100</max_points>
	<factor>1</factor>
	<is_final>0</is_final>
	<show_comments>0</show_comments>
	<grade_stats>0</grade_stats>
	<allow_dropbox>1</allow_dropbox>
	<allow_discussion>1</allow_discussion>
	<published>1</published>
	<type>assignment</type>
	<grade_item_id>5699937</grade_item_id>
	<available>1</available>
	<completed>0</completed>
	<dropbox_locked>0</dropbox_locked>
	<grading_scale_type>0</grading_scale_type>
	<show_rubric></show_rubric>
	<num_assignees>0</num_assignees>
	<assignees />
	<completion_status />
</result>

update

Modify an assignment

A few things about attachments to keep in mind when doing a PUT

  • If the "id" field is not sent in, the attachment will get deleted.
  • Only titles can be updated during a PUT
Path

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

Content

An object containing assignment fields

JSON 
{
    "title": "The assignment title with updated due date",
    "due": "2014-09-25 11:30:00",
    "attachments": [
        {
            "id": 9,
            "title": "mypicture.jpeg"
        },
        {
            "id": 11,
            "title": "title test"
        }
    ]
}
XML 
<body>
  <title>The assignment title with updated due date</title>
  <due>2014-09-28 09:30:00</due>
  <attachments>
    <id>9</id>
    <title>mypicture.jpeg</title>
  </attachments>
  <attachments>
    <id>11</id>
    <title>title test</title>
  </attachments>
</body>
Return

none

delete

Delete an assignment (cannot be undone)

Path

DELETE https://api.schoology.com/v1/sections/{section_id}/assignments/{id}

Content

none

Return

none