Skip to main content

Version: 19.05 (EOL)

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.

AttributeDescription
fetchLimitInteger (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.
fetchOffsetInteger (Default: 0)
Specify the query fetch offset.
Note: This attribute is used in conjunction with fetchLimit to determine which results are returned.
filtersList
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.

AttributeDescription
emailString
Filter users based on the email address.
Supported operators: =, IN, LIKE
firstNameString
Filter users based on the given/first name.
Supported operators: =, IN, LIKE
groupNameString / List of Strings
Filter users based on the association with groups with name(s) specified.
Supported operators: =, IN
lastNameString
Filter users based on the family/last name.
Supported operators: =, IN, LIKE
loginNameString
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 keyErrorHTTP status code
illegalArgumentUnsupported 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
internalErrorPlease see Error Log ID {number}500 Internal Server Error
unableToResolvePortalUnable to resolve portal from request400 Bad Request

Error responses

HTTP status codeDescription
400 Bad RequestBad request or request parameter. Check error message for details.
404 Not FoundEnsure the URL endpoint is entered correctly.
500 Internal Server ErrorException 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"
}
]
}