Assignment

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

Table of Contents

Fields

Field Name Description Type Required
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

Read-only: Distinguishes different types of grade items (grade items being a broad term for anything that can have a grade). This field is not supported in POST/PUT.

 {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
count_in_grade Count in Grade

Can be used for materials such as pre-assessments or practice work, allowing parents/students to see progress while knowing the score is not impacting a students calculated grade. This field can be used in a POST or PUT operation but will only get included in the response when its value and the Collected Only value are not the default.

Materials supported:

  • Assignment
  • Assessment
  • Common Assessment
  • External Tool
  • Discussion
  • Scorm Package
  • Grade Column
 {0,1} default: 1
collected_only Collected Only

Allows teachers to simply mark materials as completed or not; useful for collecting forms or documenting in-class participation. This field can be used in a POST or PUT operation but will only get included in the response when its value and the Count in Grade value are not the default.

Materials supported:

  • Assignment
  • Assessment
  • Common Assessment
  • External Tool
  • Discussion
  • Grade Column
 {0,1} default: 0
auto_publish_grades Automatically Publish Grades

Assignment grades will be visible to students and guardians as soon as they are entered.

 {0,1} default: 1

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],
  "count_in_grade": 0,
  "auto_publish_grades": 0
}
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>
  <count_in_grade>0</count_in_grade>
  <auto_publish_grades>0</auto_publish_grades>
</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,
  "count_in_grade": 0,
  "collected_only": 0,
  "auto_publish_grades": 0
  "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>
  <count_in_grade>0</count_in_grade>
  <collected_only>0</collected_only>
  <auto_publish_grades>0</auto_publish_grades>
  <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 assignments

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 ‘&limit=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,
      "count_in_grade": 1,
      "collected_only": 0,
      "auto_publish_grades": 1,
      "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>
    <count_in_grade>1</count_in_grade>
    <collected_only>0</collected_only>
    <auto_publish_grades>1</auto_publish_grades>
    <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&limit=20</self>
  </links>
</result>

list grade items

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,
          "count_in_grade": 1,
          "collected_only": 0,
          "auto_publish_grades": 1,
          "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>
        <count_in_grade>1</count_in_grade>
        <collected_only>0</collected_only>
        <auto_publish_grades>1</auto_publish_grades>
        <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&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,
  "count_in_grade": 1,
  "collected_only": 0,
  "auto_publish_grades": 1,
  "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>
  <count_in_grade>1</count_in_grade>
  <collected_only>0</collected_only>
  <auto_publish_grades>1</auto_publish_grades>
  <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