Skip to content

Add new user

POST/directory/users

Common API · Directory Management

Add a new user to the directory.

Required permissiontenant-directory.user: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
User's full name.
Must be 1–250 characters long.
firstNamestring
User's first name or given name. This must not include a space.
Must be at most 250 characters long.
lastNamestring
User's last name or surname.
Must be at most 250 characters long.
emailstring (email)
User's email address.
exchangeLoginstring
User's Exchange login.
Must be at most 350 characters long.
groupIdsarray of string (uuid)
Groups that the user should be added to.
Must contain at most 50 items. Items must be unique.
managerIdstring (uuid)
Manager in the directory to whom the current user reports.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/common/v1/directory/users" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"John Doe\",
  \"firstName\": \"John\",
  \"lastName\": \"Doe\",
  \"email\": \"jonhdoe@example.com\",
  \"exchangeLogin\": \"exchangeLogin\",
  \"groupIds\": [
    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"
  ],
  \"managerId\": \"77899dfe-38ed-417d-bc9d-2ef832e6ae4f\"
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/common/v1/directory/users",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'John Doe',
    'firstName': 'John',
    'lastName': 'Doe',
    'email': 'jonhdoe@example.com',
    'exchangeLogin': 'exchangeLogin',
    'groupIds': ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    'managerId': '77899dfe-38ed-417d-bc9d-2ef832e6ae4f'},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "jonhdoe@example.com",
  "exchangeLogin": "exchangeLogin",
  "groupIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "managerId": "77899dfe-38ed-417d-bc9d-2ef832e6ae4f"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/common/v1/directory/users" -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/users", strings.NewReader(`{
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "jonhdoe@example.com",
  "exchangeLogin": "exchangeLogin",
  "groupIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "managerId": "77899dfe-38ed-417d-bc9d-2ef832e6ae4f"
}`))
    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/users", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "jonhdoe@example.com",
  "exchangeLogin": "exchangeLogin",
  "groupIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "managerId": "77899dfe-38ed-417d-bc9d-2ef832e6ae4f"
}),
});
const data = await response.json();
console.log(data);

Responses

201 — A new user was added to the directory.

Response fields

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.

Errors

Status Meaning
404 Can't find at least one group in the request or Manager not found with given ID.
409 Email address must not already be in use. 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",
  "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"
  }
}