ManageGroup

Use this resource to complete simple queries, modify and archive group requests. The user must be an account administrator.

Method summary

HTTP Method	Path	Description
GET	/scr/api/ManageGroup	Retrieves a JSON array of all groups in the account and extracts details about a specific group.
PUT	/scr/api/ManageGroup	Adds and updates a group.
DELETE	/scr/api/ManageGroup	Archives each group individually.

GET /scr/api/ManageGroup

Description: Use this method to retrieve a JSON array of all groups in the account or to extract details about a specific group.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be an account administrator. To archive a group, the user must also have the `MANAGE` permission.
Supports OAuth 2 client credentials	Yes using a User Service ID containing User Management Category
Rate limited	Not yet

Parameters

Name	Location	Description	Required	Type
version	Header	The version of the requested API. Possible values are: `2.0` `1.0` (deprecated)	Yes	String
activeState	Query	The state of the user group. Values are `active`, `archived`, and `all`. The default value is `active`.	No	String

Response

Example input

LIST all groups in the account, including archived groups: /scr/api/ManageGroup?activeState=all

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:2.0" 
    "https://your_server_url/scr/api/ManageGroup?activeState=all"

LIST all archived groups in the account: /scr/api/ManageGroup?activeState=archived

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:2.0"  
    "https://your_server_url/scr/api/ManageGroup?activeState=archived"

GET the details of a specific group based on the group name: /scr/api/ManageGroup/group_name

Important: The group_name parameter must be properly encoded.

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:2.0"    
    "https://your_server_url/scr/api/ManageGroup/group%20admin"

LIST all active groups in the account: /scr/api/ManageGroup/

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:2.0"
    "https://your_server_url/scr/api/ManageGroup"

Example output

LIST all groups in the account:

[ 
 {
    "name": "group admin",
    "description": "This is a custom group for admins",
    "id": "4f0001",
    "activeState": "active"
  },    
  {
    "name": "group1",
    "description": "",
    "id": "4f0004",
    "activeState": "active"
  },
  {
    "name": "group2",
    "description": "",
    "id": "4f000b",
    "activeState": "active"
  },
  {
    "name": "group3",
    "description": "",
    "id": "520001",
    "activeState": "archived"
  }
]

GET the details of a specific group:

{
  "id": "4f0001",
  "name": "group admin",
  "description": "This is a custom group for admins",
  "groups": [
    {
      "name": "group2",
      "description": "",
      "id": "4f000b",
      "activeState": "active"
    },
    {
      "name": "group3",
      "description": "",
      "id": "520001",
      "activeState": "active"
    }
  ],
  "users": [
    {
      "name": "admin",
      "id": "40019",
      "email": "admin_user_email@website.com"
    },
    {
      "name": "user",
      "id": "4001e",
      "email": "super_user_email@website.com"
    }
  ]
}

Response properties

groupname: The name of the group.
description: The description of the group.
users: The list of users who are members of the group.
groups: The list of subgroups within the group.
usergroups: The list of groups in the account.
id: The ID of the group or user.
email: The email of the user.
activeState: The state of the group. Values are active and archived.

Response messages

HTTP code	Reason
200 with JSON payload	The request was completed successfully.
400 with JSON payload	There was an error processing the request. Required parameters were missing or contained invalid values.
401	The user isn't authorized to make the request.
403	Access is forbidden. This message might appear for one of the following reasons: The specified credentials are invalid. This user isn't an editor for this process. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
404	The specified GET group is not found.

PUT /scr/api/ManageGroup

Description

Use this method to add and update a group. Adding and updating a group is possible with the following methods:

The base URI behaves as an add method. The user who creates a new group becomes a member of the group and gets the MANAGE permission. If the new group is created with a Service ID, the new group has no members.
The base URI with the group name behaves as an update method.

A list of users or groups can be added as a member of the group with either one of the methods. A parent user group cannot be added as a member of its child group.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be an account administrator. To archive a group, the user must also have the `MANAGE` permission.
Supports OAuth 2 client credentials	Yes using a User Service ID containing User Management Category
Rate limited	Not yet

Parameters

Name	Location	Description	Required	Type
content-type	Header	Must be `application/json`	Yes	String
version	Header	The version of the requested API is `1.0`	Yes	String
group_name	Path	If a group name is provided in the path, the command updates the specified group name with data from the request body.	No	String
JSON Request groupname	JSON body	Defines a new added group.	Yes	String
JSON Request groups	JSON body	The array of groups to be added as members of the group.	Yes	JSON array of strings
JSON Request users	JSON body	The array of users to be added as members of the group.	Yes	JSON array of strings
JSON Request activeState	JSON body	Activates an archived group. The only valid value for this parameter is `active`. To archive an active group, use the DELETE method.	No	String
JSON Request description	JSON body	Blank description is used if none is provided.	No	String

Response

Example input

Important: The group_name parameter must be properly encoded.

Change the name of an existing group with the group name parameter in the JSON body:

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT
 --data "{\"groupname\":\"new_group_name\"}" "https://your_server_url/scr/api/ManageGroup/group2"

Add a group with a list of users and groups as members in the JSON body:

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT
 --data "{\"groupname\":\"group 10\", \"description\":\"group 10 description\", \"users\":[\"admin1\", \"user1\"], \"groups\":[\"group1\", \"group2\"]}" 
  "https://your_server_url/scr/api/ManageGroup"

Update the group with a list of users or groups:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -H "Content-Type:application/json" -X PUT    
 --data "{\"users\":[\"admin2\", \"user2\"], \"groups\":[\"group3\"]}" "https://your_server_url/scr/api/ManageGroup/group%2010"

Activate an archived group:

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:2.0" -H "Content-Type:application/json" -X PUT
 --data "{\"activeState\":\"active\"}" "https://your_server_url/scr/api/ManageGroup/group%2010"

Example output

Change the name of an existing group with the group name parameter in the JSON body:

HTTP/1.1 200 OK
Content-Length: 65
          {"groupname":"new_group_name","description":"","users":["admin"]}

Add a group with a list of users and groups as members in the JSON body:

HTTP/1.1 200 OK
Content-Length: 155
           {"groupname":"group 10","description":"group 10 description","users":["admin", "admin1", "user1"], "groups":["group1","group2"]}

Update the group with a list of users or groups:

HTTP/1.1 200 OK
Content-Length: 89
           {"groupname":"group 10","description":"","users":["admin", "user2"], "groups":["group3"]}

Activate an archived group:

HTTP/1.1 200 OK
Content-Length: 89
           {"groupname":"group 10","description":"","users":["admin", "user2"], "groups":["group3"]}

Response properties

groupname: The name of the group.
description: The description of the group.
users: The list of users who are members of the group.
groups: The list of groups that are members within the group.
activeState: The state of the group. Values are active and archived.

Response messages

HTTP code	Reason
200 with JSON payload	The request was completed successfully.
400	There was an error processing the request. Check the JSON message element for details. This message might appear for one of the following reasons: The specified user already exists. There is an issue with the format or the licensing. To archive an active user group, use the DELETE method.
401	The user isn't authorized to make the request.
403	Access is forbidden. This message might appear for one of the following reasons: The specified credentials are invalid. This user isn't an editor for this process. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
404	The specified group is not found.

DELETE /scr/api/ManageGroup

Description: Use this method to archive each group individually, to remove all users except privileged users from a group, or to remove specified users from a group. This group archiving method provides a single form of the DELETE method, and there is no support for collections. To delete multiple groups, call this method repeatedly. The user must have the MANAGE permission.

Resource information

Requirements	Description
Response format	JSON
Requires authentication	Yes. The user must be an account administrator. To archive a group, the user must also have the `MANAGE` permission.
Supports OAuth 2 client credentials	Yes using a User Service ID containing User Management Category
Rate limited	Not yet

Parameters

Name	Location	Description	Required	Type
version	Header	The version of the requested API is `1.0`	Yes	String
users/user-id	Path	The identifier of the user or users to remove from the group. Use commas to separate multiple users. To remove all users except those with Manage and Edit permissions in the group, use /users.	No	String

Response

Example input

Delete a specific group in the account: /scr/api/ManageGroup/group_name

Important: The group_name parameter must be properly encoded.

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -X DELETE 
  --data "{\"groupname\":\"new_group_name\"}" "https://your_server_url/scr/api/ManageGroup/group%20admin"

Remove all users, except those with Manage and Edit permissions, from the group: /scr/api/ManageGroup/group_name/users

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -X DELETE 
    "https://your_server_url/scr/api/ManageGroup/group%20admin/users"

Remove specific users from the group based on their user IDs. For more than one user, separate the user IDs with commas. /scr/api/ManageGroup/group_name/users/user_ID

Using OAuth 2 client credentials:

curl -i -H "Authorization: Bearer access_token" -H "Version:1.0" -X DELETE 
    "https://your_server_url/scr/api/ManageGroup/group%20admin/users/135ff2,135689"

Example output

Delete group:

HTTP/1.1 200 OK  
Content-Length: 21
            {"message":"Success"}

Delete a non-existent group:

HTTP/1.1 404 Not Found 
Content-Length: 0

Delete a group where user does not have the MANAGE permission:

HTTP/1.1 400 Bad Request 
Content-Length: 71
            {"message":"User attempted to modify group without proper permission."}

Delete users from a group:

HTTP/1.1 200 OK  
Content-Length: 21
            {"message":"Success"}

Response properties: None

Response messages

HTTP code	Reason
200 with JSON payload	The request was completed successfully.
400	There was an error processing the request. Check the JSON message element for details. This message might appear for one of the following reasons: The user ID is not valid or the user cannot be found. The user does not belong to the group. The user has Manage and Edit permissions for the group and cannot be removed.
401	The user isn't authorized to make the request.
403	Access is forbidden. This message might appear for one of the following reasons: The specified credentials are invalid. This user isn't an editor for this process. APIs aren't enabled by the administrator. APIs must be enabled on the Account Information tab. The administrator didn't accept the Terms and Conditions of service.
404	The requested group is not found.