POST Query User

Return a list of users, filtered on the specified criteria.

This API only returns user accounts that:

• have the global access flag checked, or are associated with organizations the current user belongs to, and
• are associated with the current portal

The results are ordered alphabetically by loginName.

Request

HTTP request

POST https://<JM_SERVER>/workspaces/secure/api/v1/user/query

Request body

The POST request must contain a JSON structure describing the user query. To support multiple parameters, this API uses HTTP Content Type: application/json.

The available query attributes are listed below. All attributes are optional except where otherwise indicated.

Attribute	Description
fetchLimit	Integer (Default: 10000) Required. Specify the query fetch limit; that is, the maximum number of results returned. Values: In the range 1 - 10,000. Values greater than 10,000 are reduced to 10,000. Note: This attribute is used in conjunction with fetchOffset to determine which results are returned.
fetchOffset	Integer (Default: 0) Specify the query fetch offset. Note: This attribute is used in conjunction with fetchLimit to determine which results are returned.
filters	List A list of filters to query users by. To learn more about query filters, see Filter query results.

Supported filter criteria attributes

The supported filter criteria attributes are listed below.

caution

If you specify an invalid attribute, a 400 Bad Request HTTP status code is returned.

Attribute	Description
email	String Filter users based on the email address. Supported operators: =, IN, LIKE
firstName	String Filter users based on the given/first name. Supported operators: =, IN, LIKE
groupName	String / List of Strings Filter users based on the association with groups with name(s) specified. Supported operators: =, IN
lastName	String Filter users based on the family/last name. Supported operators: =, IN, LIKE
loginName	String Filter users based on the loginName. Supported operators: =, IN, LIKE

Response

If successful, this operation returns a response with a HTTP 200 OK status code.

Error messages

Error key	Error	HTTP status code
illegalArgument	Unsupported criteria attribute: <ATTRIBUTE> Unsupported operator for attribute '<ATTRIBUTE>': <OPERATOR> For input string: <STRING> User Account not found Please see Error Log ID {number}	400 Bad Request
internalError	Please see Error Log ID {number}	500 Internal Server Error
unableToResolvePortal	Unable to resolve portal from request	400 Bad Request

Error responses

HTTP status code	Description
400 Bad Request	Bad request or request parameter. Check error message for details.
404 Not Found	Ensure the URL endpoint is entered correctly.
500 Internal Server Error	Exception occurred in user query. Contact administrator.

Example

Complex queries can be created by joining multiple filter criteria using "AND" or "OR" operators. For examples of how to define these queries, see Filter query results.

Ensure you specify Content-Type: application/json.

Example request 1

POST /workspaces/secure/api/v1/user/query HTTP/1.1
Host: https://transact.workspaces.com
Content-Type: application/json

{
    "fetchLimit": 100,
    "fetchOffset": 0,
    "filters": [
        {
            "criteria" : [
                "loginName = 'testUser'",
                "firstName = 'tester'"
            ],
            "operator": "or"
        }
    ]
}

Example reqeust 2

POST /workspaces/secure/api/v1/user/query HTTP/1.1
Host: https://transact.workspaces.com
Content-Type: application/json

{
    "fetchLimit": 100,
    "fetchOffset": 0,
    "filters": [
        {
            "criteria" : [
                "loginName = {0}",
                "firstName = {1}"
            ],
            "params": [
                "testUser",
                "tester"
            ],
            "operator": "or"
        }
    ]
}

Example request 3

POST /workspaces/secure/api/v1/user/query HTTP/1.1
Host: https://transact.workspaces.com
Content-Type: application/json

{
    "fetchLimit": 100,
    "fetchOffset": 0,
    "filters": [
        {
            "criteria" : [
                "email like 'test'",
                "email like '@avoka.com'"
            ],
            "operator": "and"
        }
    ]
}

All of the above example requests produce the following response.

Example successful response

{
    "fetchLimit": 100,
    "fetchOffset": 0,
    "durationMs": 13,
    "result": [
        {
            "email": "[email protected]",
            "firstName": "firstName",
            "lastName": "lastName",
            "loginName": "testUser",
            "mobile": "0400123123",
            "userKey": "4d393a76701785ac6afab976bec41d9a"
        },
        {
            "email": "[email protected]",
            "firstName": "Tester",
            "lastName": "lastName",
            "loginName": "[email protected]",
            "userKey": "36cdbda28358b8e22a5aa2553b4adf21"
        }
    ]
}