Search Users

Searches users according to the specified criteria.

Request

HTTP Request

POST /node/api/users/search

Permissions

manage-users

Path parameters

No parameters required.

Body parameters

You can filter users by any field of the user. See the User model for all available fields.

Filters can use MongoDB’s Query and Projection Operators

Request body

Request body contains a MongoDB query that filters users by their fields.

A request with an empty filter returns all users in the system. 
{
    "status": 2,
    "language": "en",
    "permissions": {
        "$regex": "delete",
        "$options": "i"
    }
}

Email field

You can search email by either a full email or by a part of it. Note that this filter isn’t available for any other field.

  • Full email

  • Part of email

{
    "email": "email@example.com",
}
{
    "email": { "contains": "@example.com" }
}
Both email filters are case-insensitive.

Nested objects

You can’t search users by a field of a nested object.

For example, you can’t search users by the include field of the objectPermissions object. You have to specify the whole object and the match have to be exact.

{
    "objectPermissions": {
        "include": [
            1,
            "6151bf7bc6efdc7ac9d86fe2"
        ]
    }
}

The filter above would include the first user, but not the second:

{
    "id": "55e59fbe7d0ce76f660607b8""login": "user 1",
    ...
    "objectPermissions": {
        "include": [
            1,
            "6151bf7bc6efdc7ac9d86fe2"
        ]
    }
},
{
    "id": "55e59fbe7d0ce76f660607b9""login": "user 2",
    ...
    "objectPermissions": {
        "include": [
            1,
            "6151bf7bc6efdc7ac9d86fe2"
        ],
        "exclude": [] // This user wouldn't match the filter because of this empty array
    }
}

Response

This request returns an array of users that match the specified search criteria.

Example

Request

  • Bash

  • JavaScript

  • NodeJS

  • Python

login=<...>
password=<...>
saymon_hostname=<...>
url=https://$saymon_hostname/node/api/users/search

curl -X POST $url -u $login:$password \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
  'status': 2,
  'email': { 'contains': 'gmail' },
    'permissions': { '$regex': 'delete', '$options': 'i' }
}
EOF
let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/users/search";
let auth = "Basic " + btoa(login + ":" + password);

let headers = new Headers();
headers.append("Content-Type", "application/json");
headers.append("Authorization", auth);

let data = JSON.stringify({
  'status': 2,
  'email': { 'contains': 'gmail' },
    'permissions': { '$regex': 'delete', '$options': 'i' }
});

let requestOptions = {
    method: "POST",
    headers: headers,
    body: data
};

fetch(saymonHostname + path, requestOptions)
    .then(response => response.text())
    .then(result => console.log(result))
    .catch(error => console.log("error", error));
const http = require("http");

let login = <...>
let password = <...>
let saymonHostname = <...>
let path = "/node/api/users/search";
let auth = "Basic " + Buffer.from(login + ":" + password).toString("base64");

let options = {
    "method": "POST",
    "hostname": saymonHostname,
    "headers": {
        "Authorization": auth,
        "Content-Type": "application/json"
    },
    "path": path
};

let req = http.request(options, function (res) {
    let chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        let body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

let data = JSON.stringify({
  'status': 2,
  'email': { 'contains': 'gmail' },
    'permissions': { '$regex': 'delete', '$options': 'i' }
});

req.write(data);
req.end();
import requests

login = <...>
password = <...>
saymon_hostname = <...>
url = "https://" + saymon_hostname + "/node/api/users/search"

body = {
    'status': 2,
    'email': { 'contains': 'gmail' },
    'permissions': { '$regex': 'delete', '$options': 'i' }
}

response = requests.request("POST", url, json=body, auth=(login, password))
print(response.text)

Response

[
    {
        "contacts": [],
        "email": "user_email@example.com",
        "eventFilter": [],
        "id": "5ac7ac5c6402b51c27548e5b",
        "login": "user_login",
        "objectPermissions": {
            "exclude": [
                "5e84d212866ec23538893061"
            ],
            "include": [
                "817",
                "5e84d165866ec23538892f7d",
                "5ec7aab16402b70c27448e64"
            ]
        },
        "permissions": [
            "manage-objects",
            'delete-objects',
            "manage-links",
            "manage-service-properties",
            "view-section-stat",
            "view-section-monitoring",
            "view-section-history-graph"
        ],
        "status": 2
    }
]

See Also