Skip to content

Add new group

POST/directory/user-groups

Common API · Directory Management

Add a new group to the directory.

Required permissiontenant-directory.user-group:create AND tenant-directory.membership:add

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
fields query array of string No The fields to return in a partial response.

Request body

Content type: application/json

Request body fields

namestringrequired
Group name.
Must be 1–250 characters long.
descriptionstring
Group description.
Must be at most 1000 characters long.
userIdsarray of string (uuid)
Users in the group.
Must contain at most 1000 items. Items must be unique.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/common/v1/directory/user-groups" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"Sophos Central Group\",
  \"description\": \"Security group for Sophos Central admins\",
  \"userIds\": [
    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"
  ]
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/common/v1/directory/user-groups",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'Sophos Central Group',
    'description': 'Security group for Sophos Central admins',
    'userIds': ['3fa85f64-5717-4562-b3fc-2c963f66afa6']},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "Sophos Central Group",
  "description": "Security group for Sophos Central admins",
  "userIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/common/v1/directory/user-groups" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/common/v1/directory/user-groups", strings.NewReader(`{
  "name": "Sophos Central Group",
  "description": "Security group for Sophos Central admins",
  "userIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/common/v1/directory/user-groups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Sophos Central Group",
  "description": "Security group for Sophos Central admins",
  "userIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses

201 — Group created.

Response fields

idstring (uuid)required
Group ID.
namestringrequired
Group name.
displayNamestring
Display name.
descriptionstring
Group description.
domainstring
Domain name.
groupsobject
Associated groups.
Show child attributesHide child attributes
totalinteger
itemsCountinteger
itemsarray of object
Items must be unique.
Group reference.
Show child attributesHide child attributes
idstring (uuid)required
Group ID.
namestring
Group name.
displayNamestring
Display name.
sourceobjectrequired
Source of directory information.
Show child attributesHide child attributes
typestring (enum)required
Types of sources of directory information. All users and groups created using this API have the source type custom. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type activeDirectory, azureActiveDirectory or googleDirectory respectively.
Must be one of: custom, activeDirectory, azureActiveDirectory, googleDirectory.
usersobject
Associated users.
Show child attributesHide child attributes
totalinteger
itemsCountinteger
itemsarray of object
Items must be unique.
Reference to the user.
Show child attributesHide child attributes
idstring (uuid)required
User ID.
namestring
User's full name.
tenantobjectrequired
Reference to a tenant.
Show child attributesHide child attributes
idstring (uuid)required
Tenant ID.
namestring
Tenant Name.
createdAtstring (datetime)
When the group was created.
updatedAtstring (datetime)
When the group was last updated.

Errors

Status Meaning
404 Can't find at least one user in the request.
409 Group names must be unique. You also can't use this API to add users to a group synced from Active Directory.
500 Internal server error.

All error responses share the same shape — see the error response object.

Response examples

201

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "displayName": "string",
  "description": "string",
  "domain": "string",
  "groups": {
    "total": 0,
    "itemsCount": 0,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "displayName": "string"
      }
    ]
  },
  "source": {
    "type": "custom"
  },
  "users": {
    "total": 0,
    "itemsCount": 0,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "string"
      }
    ]
  },
  "tenant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "string"
  },
  "createdAt": "string",
  "updatedAt": "string"
}