Group

Groups are non-academic versions of course sections; they can hold members, events, documents, etc.

Table of Contents

Fields

Field Name Description Type Required
id Schoology Group ID

The internal Schoology ID of the group

string no
building_id Schoology School Building ID

The internal Schoology ID of the school building to which the group belongs

string no
school_id Schoology School ID

The internal Schoology ID of the school to which the group belongs

string no
title Group Title

The title of the group

string yes
description Description

The group description

string
picture_url Picture

The URL of the group’s profile picture

string
website Website

The group website

string
access_code Access Code

The access code that users can use to join the group (only admins can see this value).

string
privacy_level Privacy level

The privacy of the group.

  • everyone: All schoology users can see the group.
  • school: Only members of the school can see the group
  • building: Only members of the building can see the group
  • group: Only group members can see the group
  • custom: Custom privacy settings (read only; not supported in POST/PUT)
{everyone, school, building, group} Default: school
category Category

The category of the group (see below on how to retrieve a list of available categories)

string no
options/invite_type Invite Type

How members can join the group.

  • 0: Invite only
  • 1: Request to join
  • 2: Anyone can join
{0-2} Default: 0
options/member_post Post a group update

Whether or not a group member can post a group update

{0,1} Default: 1
options/member_post_comment Post a comment on a group update

Whether or not a group member can post comments to group udpates

{0,1} Default: 1
options/create_discussion Create a discussion thread

Whether or not a group member can create a discussion thread

{0,1} Default: 0
options/create_files Create files

Whether or not members can create resources for the group

{0,1} Default: 0
group_code Group Code (external ID)

If the group was imported from another system into Schoology, the unique ID of that group in the other system.

string

Operations

create

Create a group

Path

POST https://api.schoology.com/v1/groups

Content

An object containing group fields

JSON
{
    "title": "My new group",
    "description": "discuss new groups",
    "website": "http:\/\/www.newgroup.com",
    "picture_url": "http:\/\/www.newgroup.com\/profile-pic.gif"
}
XML
<body>
  <title>My new group</title>
  <description>discuss new groups</description>
  <website>http://www.newgroup.com</website>
  <picture_url>http://www.newgroup.com/profile-pic.gif</picture_url>
</body>
Return

An object containing group fields

JSON
{
    "id": "5604275",
    "title": "Google News",
    "description": "discuss latest news",
    "website": "",
    "access_code": "QM6JC-D7VKK",
    "category": null,
    "options": {
        "member_post": 1,
        "member_post_comment": 1,
        "create_discussion": 0,
        "create_files": 0,
        "invite_type": 0
    },
    "group_code": "",
    "picture_url": "http:\/\/...group-default.gif",
    "school_id": "344232",
    "building_id": "344232",
    "links": {
        "self": "http:\/\/...\/v1\/groups\/5604275"
    }
}
XML
<?xml version="1.0" encoding="utf-8" ?>
<result>
  <id>5604275</id>
  <title>Google News</title>
  <description>discuss latest news</description>
  <website />
  <access_code>QM6JC-D7VKK</access_code>
  <category />
  <options>
    <member_post>1</member_post>
    <member_post_comment>1</member_post_comment>
    <create_discussion>0</create_discussion>
    <create_files>0</create_files>
    <invite_type>0</invite_type>
  </options>
  <group_code />
  <picture_url>http://...f</picture_url>
  <school_id>344232</school_id>
  <building_id>344232</building_id>
  <links>
    <self>http://.../v1/groups/5604275</self>
  </links>
</result>

list

View a list of groups in your school (paged). You can use the following parameters to filter the resultset:

  • building_id: return only groups for the given building_id.
Path

GET https://api.schoology.com/v1/groups

Content

none

Return

A collection of group objects, each one containing group fields

JSON
{
    "group": [
        {
            "id": "5604383",
            "title": "Google News group",
            "description": "Google News group",
            "website": "",
            "access_code": "H2QSM-CJPXD",
            "category": "",
            "options": {
                "member_post": 1,
                "member_post_comment": 1,
                "create_discussion": 1,
                "create_files": 0,
                "invite_type": 0
            },
            "group_code": "",
            "picture_url": "http:\/\/...group-default.gif",
            "school_id": "344232",
            "building_id": "344232",
            "links": {
                "self": "http:\/\/...\/v1\/groups\/5604383"
            }
        }
    ],
    "total": 1,
    "links": {
        "self": "http:\/\/...\/v1\/groups?start=0&limit=20"
    }
}
XML
<?xml version="1.0" encoding="utf-8" ?>
<result>
  <group>
    <id>5604383</id>
    <title>Google News group</title>
    <description>Google News group</description>
    <website />
    <access_code>H2QSM-CJPXD</access_code>
    <category />
    <options>
      <member_post>1</member_post>
      <member_post_comment>1</member_post_comment>
      <create_discussion>1</create_discussion>
      <create_files>0</create_files>
      <invite_type>0</invite_type>
    </options>
    <group_code />
    <picture_url>http://...group-default.gif</picture_url>
    <school_id>344232</school_id>
    <building_id>344232</building_id>
    <links>
      <self>http://.../v1/groups/5604383</self>
    </links>
  </group>
  <total>1</total>
  <links>
    <self>http://.../v1/groups?start=0&amp;limit=20</self>
  </links>
</result>

view

View a specified group

Path

GET https://api.schoology.com/v1/groups/{id}

Content

none

Return

An object containing group fields

JSON
{
    "id": "5604383",
    "title": "Google News group",
    "description": "Google News group",
    "website": "",
    "access_code": "H2QSM-CJPXD",
    "category": "",
    "options": {
        "member_post": 1,
        "member_post_comment": 1,
        "create_discussion": 1,
        "create_files": 0,
        "invite_type": 0
    },
    "group_code": "",
    "picture_url": "http:\/\/...\/images\/group-default.gif",
    "school_id": "344232",
    "building_id": "344232"
}
XML
<?xml version="1.0" encoding="utf-8" ?>
<result>
  <id>5604383</id>
  <title>Google News group</title>
  <description>Google News group</description>
  <website />
  <access_code>H2QSM-CJPXD</access_code>
  <category />
  <options>
    <member_post>1</member_post>
    <member_post_comment>1</member_post_comment>
    <create_discussion>1</create_discussion>
    <create_files>0</create_files>
    <invite_type>0</invite_type>
  </options>
  <group_code />
  <picture_url>http://...s/group-default.gif</picture_url>
  <school_id>344232</school_id>
  <building_id>344232</building_id>
</result>

update

Modify a group

Path

PUT https://api.schoology.com/v1/groups/{id}

Content

An object containing group fields

JSON
{
    "title": "My new group name updated",
    "picture_url": "http:\/\/www.newgroup.com\/new-pic.gif"
}
XML
<body>
  <title>My new group name updated</title>
  <picture_url>http://www.newgroup.com/newpic.gif</picture_url>
</body>
Return

none

delete

Delete a group (cannot be undone)

Path

DELETE https://api.schoology.com/v1/groups/{id}

Content

none

Return

none

list group categories

View a list of group categories.

Path

GET https://api.schoology.com/v1/groups/categories

Content

none

Return

A collection of category objects, each one containing category fields

JSON
{
    "category": [
        {
            "id": "abroad",
            "title": "Abroad\/Overseas Groups"
        },
        {
            "id": "advising",
            "title": "Advising Groups"
        },
        {
            "id": "alumni",
            "title": "Alumni Groups"
        },
        {
            "id": "career",
            "title": "Career Groups"
        },
        {
            "id": "extracurricular",
            "title": "Extracurricular Groups"
        }
    ]
}
XML
<?xml version="1.0" encoding="utf-8" ?>
<result>
	<category>
		<id>abroad</id>
		<title>Abroad/Overseas Groups</title>
	</category>
	<category>
		<id>advising</id>
		<title>Advising Groups</title>
	</category>
	<category>
		<id>alumni</id>
		<title>Alumni Groups</title>
	</category>
	<category>
		<id>career</id>
		<title>Career Groups</title>
	</category>
	<category>
		<id>extracurricular</id>
		<title>Extracurricular Groups</title>
	</category>
</result>