Groups API

The Groups API allows you to manage groups of users via the API.


Add Member

Endpoint HTTP Method
2.0/groups/add-member POST

Adds a user or group to a group. This call returns an error RESOURCE_DOES_NOT_EXIST if a user or group with the given name does not exist, or if a group with the given parent name does not exist.

Example requests:

{
  "user_name": "hermione@hogwarts.edu",
  "parent_name": "Gryffindor"
}
{
  "group_name": "Dumbledore's Army",
  "parent_name": "Students"
}

Request Structure

Field Name Type Description
user_name OR group_name STRING OR STRING

If user_name, the user name.

If group_name, the group name.

parent_name STRING Name of the parent group to which the new member will be added. This field is required.

Create

Endpoint HTTP Method
2.0/groups/create POST

Creates a new group with the given name. This call returns an error RESOURCE_ALREADY_EXISTS if a group with the given name already exists.

Example request:

{
  "group_name": "Muggles"
}

Example response:

{
  "group_name": "Muggles"
}

Request Structure

Field Name Type Description
group_name STRING Name for the group; must be unique among groups owned by this organization. This field is required.

Response Structure

Creates a group.

Field Name Type Description
group_name STRING The group name.

List Members

Endpoint HTTP Method
2.0/groups/list-members GET

Returns all of the members of a particular group. This call returns an error RESOURCE_DOES_NOT_EXIST if a group with the given name does not exist.

Example request:

{
  "group_name": "Gryffindor"
}

Example response:

{
  "members": [
    { "user_name": "hjp@hogwarts.edu" },
    { "user_name": "hermione@hogwarts.edu" },
    { "user_name": "rweasley@hogwarts.edu" },
    { "group_name": "Gryffindor Faculty" }
  ]
}

Request Structure

Field Name Type Description
group_name STRING The group whose members we want to retrieve. This field is required.

Response Structure

Retrieves all users and groups that belong to a given group (note: this method is non-recursive - it will return all groups that belong to the given group but not the principals that belong to those child groups).

Field Name Type Description
members An array of PrincipalName The users and groups that belong to the given group.

List

Endpoint HTTP Method
2.0/groups/list GET

Returns all of the groups in an organization.

Example response:

{
  "group_names": [
    "admin",
    "Gryffindor",
    "Hufflepuff",
    "Ravenclaw",
    "Slytherin"
  ]
}

Response Structure

Returns a list of all groups in this organization.

Field Name Type Description
group_names An array of STRING The groups in this organization.

List Parents

Endpoint HTTP Method
2.0/groups/list-parents GET

Retrieves all groups in which a given user or group is a member (note: this method is non-recursive - it will return all groups in which the given user or group is a member but not the groups in which those groups are members). This call returns an error RESOURCE_DOES_NOT_EXIST if a user or group with the given name does not exist.

Example request:

{
  "user_name": "hermione@hogwarts.edu"
}

Example response:

{
  "group_names": [
    "users",
    "Wizards",
    "Gryffindor",
    "Dumbledore's Army"
  ]
}

Example request:

{
  "group_name": "Gryffindor Faculty"
}

Example response:

{
  "group_names": [
    "Faculty",
    "Gryffindor"
  ]
}

Request Structure

Field Name Type Description
user_name OR group_name STRING OR STRING

If user_name, the user name.

If group_name, the group name.

Response Structure

Retrieves all groups in which a given user or group is a member (note: this method is non-recursive - it will return all groups in which the given user or group is a member but not the groups in which those groups are members).

Field Name Type Description
group_names An array of STRING The groups in which the given user or group is a member.

Remove Member

Endpoint HTTP Method
2.0/groups/remove-member POST

Removes a user or group from a group. This call returns an error RESOURCE_DOES_NOT_EXIST if a user or group with the given name does not exist, or if a group with the given parent name does not exist.

Example requests:

{
  "user_name": "quirrell@hogwarts.edu",
  "parent_name": "Faculty"
}
{
  "group_name": "Inquisitorial Squad"
  "parent_name": "Students"
}

Request Structure

Field Name Type Description
user_name OR group_name STRING OR STRING

If user_name, the user name.

If group_name, the group name.

parent_name STRING Name of the parent group from which the member will be removed. This field is required.

Delete

Endpoint HTTP Method
2.0/groups/delete POST

Removes a group from this organization. This call returns an error RESOURCE_DOES_NOT_EXIST if a group with the given name does not exist.

Example request:

{
  "group_name": "Inquisitorial Squad"
}

Request Structure

Field Name Type Description
group_name STRING The group to remove. This field is required.

Data Structures

PrincipalName

Container type for a name that is either a user name or a group name.

Field Name Type Description
user_name OR group_name STRING OR STRING

If user_name, the user name.

If group_name, the group name.