Skip to content

Query users

GET/directory/users

Common API · Directory Management

List users in the directory.

Required permissiontenant-directory.user:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
sort query array of string No Comma-separated list of sort criteria for users. Valid sort fields are id, name, firstName, lastName, email, exchangeLogin, createdAt, and updatedAt. You can append ':asc' or ':desc' to each field to specify the sort direction. The default sort direction for each field is unspecified.
Each item must match the pattern (^[^:]+$)|(^[^:]+:(asc|desc)$).
fields query array of string No The fields to return in a partial response.
page query integer No The page number to fetch, starting with 1.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.
pageSize query integer No Size of the page requested.
Must be ≥ 1 and ≤ 100.
ids query array of string (uuid) No List of item IDs to match.
Must contain at most 50 items. Items must be unique.
search query string No Search for items that match the given terms.
searchFields query array of string (enum) No Search only within the specified fields. When not specified, the default behavior is to search the full names of users, only.
Each item must be one of: name, firstName, lastName, email, exchangeLogin.
sourceType query string (enum) No Source directory type.
Must be one of: custom, activeDirectory, azureActiveDirectory, googleDirectory.
groupId query string (uuid) No Search for users in a group that has this ID.
domain query string No List the items that match the given domain.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/common/v1/directory/users" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/common/v1/directory/users",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/common/v1/directory/users" -Headers $headers


package main

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

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/common/v1/directory/users", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    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/users", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — Page of users.

Response fields

itemsarray of objectrequired
User in the directory.
Show child attributesHide child attributes
idstring (uuid)required
User ID.
namestringrequired
User's name.
firstNamestring
User's first name or given name.
lastNamestring
User's last name or surname.
emailstring
User's email address.
domainstring
Domain name.
exchangeLoginstring
User's Exchange login.
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.
tenantobjectrequired
Reference to a tenant.
Show child attributesHide child attributes
idstring (uuid)required
Tenant ID.
namestring
Tenant 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.
createdAtstring (datetime)
When the user was created.
updatedAtstring (datetime)
When the user was last updated.
managerobject
Manager in the directory.
Show child attributesHide child attributes
idstring (uuid)
Manager ID.
namestring
Manager name.
pagesobjectrequired
Show child attributesHide child attributes
currentintegerrequired
The 1-based page number being returned.
sizeintegerrequired
The size of the page being returned.
totalinteger
(Optional) The total number of pages that exist, if pageTotal=true in the request.
itemsinteger
(Optional) The total number of items across all pages.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
500 Internal server error.

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

Response examples

200

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "domain": "string",
      "exchangeLogin": "string",
      "groups": {
        "total": 0,
        "itemsCount": 0,
        "items": [
          {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "string",
            "displayName": "string"
          }
        ]
      },
      "tenant": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "string"
      },
      "source": {
        "type": "custom"
      },
      "createdAt": "string",
      "updatedAt": "string",
      "manager": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "string"
      }
    }
  ],
  "pages": {
    "current": 0,
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  }
}