---
title: PUT User Search
slug: put-user-search
createdAt: 2024-10-16T17:25:27.594Z
---
Entity Management (EM) contains User data that is associated to groups and roles. The user, group, role and permission records work in conjunction with each other to control workflow activities and what users can or cannot do within the system. Roles and users are associated to groups using Group Management, and permissions are associated to roles using Role Management.
For more information about the data driving this function, refer to the EM Application Data document.
***
:::ApiMethodV2
```json
{
"name": "Search Users",
"method": "PUT",
"url": "/api/v4/user-access/users/search",
"description": "The purpose of the PUT Search User API is for the client to obtain a complete listing of all groups, permissions, and roles for users from the server. The response also includes user preferences such as preferred language and page size. While the intended purpose is to retrieve information about a specific user, it may also be used to retrieve the same information for all users or users within a certain group or any other user attribute. This API mimics searching for a user under Administration → User Management in Entity Management.",
"tab": "examples",
"examples": {
"languages": [
{
"id": "8VTitnJCvptMIL5CXkbXI",
"language": "json",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"Accept\", \"application/json\");\nmyHeaders.append(\"Content-Type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"id\": \"String\"\n});\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.cakes.com\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));",
"customLabel": ""
},
{
"id": "Ktyf05EQ16nkvXvb5QYkV",
"language": "curl",
"code": "curl --location --request PUT 'https://baseurl/api/v4/user-access/users/search' \\\n--header 'Content-Type: String' \\\n--data '{\"start\":\"Integer\",\"limit\":\"Integer\",\"returnNullFields\":\"Boolean\",\"returnSearchResults\":\"String\",\"filters\":\"Array\"}'",
"customLabel": ""
},
{
"id": "xeJVVvKzXQLX2wmi4J5dG",
"language": "nodejs",
"code": "var request = require('request');\nvar options = {\n 'method': 'PUT',\n 'url': 'https://baseurl/api/v4/user-access/users/search',\n 'headers': {\n 'Content-Type': 'String'\n },\n body: '{\"start\":\"Integer\",\"limit\":\"Integer\",\"returnNullFields\":\"Boolean\",\"returnSearchResults\":\"String\",\"filters\":\"Array\"}'\n\n};\nrequest(options, function (error, response) {\n if (error) throw new Error(error);\n console.log(response.body);\n});\n",
"customLabel": ""
},
{
"id": "ycmWfFFKXT8oDgp18ihl4",
"language": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"Content-Type\", \"String\");\n\nvar raw = \"{\\\"start\\\":\\\"Integer\\\",\\\"limit\\\":\\\"Integer\\\",\\\"returnNullFields\\\":\\\"Boolean\\\",\\\"returnSearchResults\\\":\\\"String\\\",\\\"filters\\\":\\\"Array\\\"}\";\n\nvar requestOptions = {\n method: 'PUT',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://baseurl/api/v4/user-access/users/search\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));",
"customLabel": ""
},
{
"id": "lGPjl21rdZ0UTM9SjG3b9",
"language": "python",
"code": "import requests\n\nurl = \"https://baseurl/api/v4/user-access/users/search\"\n\npayload = \"{\\\"start\\\":\\\"Integer\\\",\\\"limit\\\":\\\"Integer\\\",\\\"returnNullFields\\\":\\\"Boolean\\\",\\\"returnSearchResults\\\":\\\"String\\\",\\\"filters\\\":\\\"Array\\\"}\"\nheaders = {\n 'Content-Type': 'String'\n}\n\nresponse = requests.request(\"PUT\", url, headers=headers, data=payload)\n\nprint(response.text)\n",
"customLabel": ""
},
{
"id": "1te54W-cC7ofAFVmIaDNj",
"language": "ruby",
"code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"https://baseurl/api/v4/user-access/users/search\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Put.new(url)\nrequest[\"Content-Type\"] = \"String\"\nrequest.body = \"{\\\"start\\\":\\\"Integer\\\",\\\"limit\\\":\\\"Integer\\\",\\\"returnNullFields\\\":\\\"Boolean\\\",\\\"returnSearchResults\\\":\\\"String\\\",\\\"filters\\\":\\\"Array\\\"}\"\n\nresponse = https.request(request)\nputs response.read_body\n",
"customLabel": ""
}
],
"selectedLanguageId": "8VTitnJCvptMIL5CXkbXI"
},
"results": {
"languages": [
{
"id": "9twpBCQ7DY3tluMIu5CXR",
"language": "200",
"customLabel": "",
"code": "{\n \"name\": \"Cake's name\",\n}"
},
{
"id": "hH1_t9x1YWSqU27BQSZ0U",
"language": "404",
"customLabel": "",
"code": "{\n \"message\": \"Ain't no cake like that.\"\n}"
}
],
"selectedLanguageId": "9twpBCQ7DY3tluMIu5CXR"
},
"request": {
"pathParameters": [
{
"name": "baseurl",
"kind": "required",
"type": "string",
"description": "The URL of the system environment target.",
"children": []
},
{
"name": "token",
"kind": "required",
"type": "string",
"description": "The authentication access token.",
"children": []
}
],
"queryParameters": [],
"headerParameters": [
{
"name": "Content-Type",
"kind": "required",
"type": "string",
"description": "application/json",
"children": []
},
{
"name": "Accept",
"kind": "required",
"type": "string",
"description": "*/*",
"children": []
}
],
"bodyDataParameters": [
{
"name": "start",
"kind": "optional",
"type": "Integer",
"description": "The default value is 0 and indicates the results start from the beginning. The start is not required unless the user desires a different value for pagination purposes.",
"children": []
},
{
"name": "limit",
"kind": "optional",
"type": "Integer",
"description": "The default value is 50 and indicates the number of results returned in the response. The limit is not required unless a different value is desired, up to the maximum of 1000. ",
"children": []
},
{
"name": "returnNullFields",
"kind": "optional",
"type": "Boolean",
"description": "Indicates whether empty/null fields should be returned in the response. The default value is false when not provided. ",
"children": []
},
{
"name": "returnSearchResults",
"kind": "optional",
"type": "String",
"description": "The value DEFAULT is used if not provided in the request. The user may request a different level of return information using the following values:\n\nDEFAULT - Returns the configured default fields. NOTE: The client environment may be configured with different default fields.\n\nBASIC - Returns DEFAULT fields plus additional fields. NOTE: The client environment may be configured with different basic fields.\n\nFULL - Returns all designated user fields.",
"children": []
},
{
"name": "filters",
"kind": "optional",
"type": "Array",
"description": "The list of field:values pairs used to narrow the search response results in addition to queries fields and values. The filters array is not required. ",
"children": []
},
{
"name": "values",
"kind": "optional",
"type": "string",
"description": "The field name to be used as a filter in the search request. The fields available for use in the filters array are indicated as Filters/Queries in the User Search Fields table.",
"children": []
},
{
"name": "queries",
"kind": "required",
"type": "Array",
"description": "The list of field:values pairs used to narrow the search response results. The queries array is required. Note: The field allnames with a value of ~ must be used if no other specific search criteria is desired. This field:values pair returns all user records. ",
"children": []
},
{
"name": "field",
"kind": "required",
"type": "string",
"description": "The field name to be used in the search query. The fields available for use in the queries array are indicated as Filters/Queries in the User Search Fields table. The field allnames is a special search field to indicate all user name fields are searched without having to list each field separately (i.e., username, first name, last name, email).",
"children": []
},
{
"name": "values",
"kind": "required",
"type": "string",
"description": "The value to be searched for in the respective field. Use ~ if no specific values are requested for allnames.",
"children": []
},
{
"name": "orders",
"kind": "optional",
"type": "Array",
"description": "The orders array is optional. The field:direction pairs provided in the array indicates the field and order of the results. The default sort order (display name, ascending) will be used when orders is not provided.",
"children": []
},
{
"name": "field",
"kind": "optional",
"type": "string",
"description": "The field name to order the response on. One or more field:direction pairs may be provided in the orders array. The fields available for use in the orders array are indicated as Orders in the User Search Fields table. ",
"children": []
},
{
"name": "direction",
"kind": "optional",
"type": "string",
"description": "The value ASC is used to indicate ascending order and the value DESC is used to indicate descending order.",
"children": []
},
{
"name": "sortPriority",
"kind": "optional",
"type": "Integer",
"description": "Indicates the orders field priority related to sorting.",
"children": []
}
],
"formDataParameters": []
},
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"response": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "ID of the cake retrieved"
}
]
}
```
:::
### Return Search Results
:::ExpandableHeading{isOpen="true"}
DEFAULT return fields
- User ID
- Is active
- Username
- Email
- Display name
- First name
- Last name
- Country
- Effective date
:::
:::ExpandableHeading{isOpen="true"}
BASIC return fields - everything in DEFAULT plus:
- Last synchronized date
- Last user agreement date
- Member firm ID
- Member firm name
- External source ID
- External HR user ID
- IdP user ID
- IdP ID
- Preferred language (ID)
- Preferred language value
- Preferred page size (ID)
- Preferred page size value
:::
:::ExpandableHeading{isOpen="true"}
FULL return fields - everything in DEFAULT and BASIC plus:
- Office
- Location override ID
- Location override value
- Is supervisor
- Group list
- Role list
- Permission list
:::
### User Search Fields
The table below outlines the fields supported for use in the queries array, filters array, and/or orders array as indicated in the Description column (Filters/Queries, Orders).
:::ExpandableHeading{isOpen="true"}
Supported Search Fields
| Field | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allnames `string` | `Filters/Queries`
A special-purpose field to search upon for the provided value(s) against all name types (e.g., first, last, username, display name) without having to provide each field in the request. |
| firstname `string` | `Filters/Queries` `Orders`
The first name of the user. |
| lastname `string` | `Filters/Queries` `Orders`
The last name of the user. |
| id `integer` | `Filters/Queries` `Orders`
The unique object identifier of the user profile object. |
| externalhruserid `string` | `Filters/Queries` `Orders`
An external user ID that may be used by the client organization to identify the user. |
| username `string` | `Filters/Queries` `Orders`
The user name of the user. This is dependent on what the client organization uses as the username to identify the user. |
| email `string` | `Filters/Queries` `Orders`
The email address of the user. This value must be unique within the application. |
| country `string` | `Filters/Queries` `Orders`
The name of the country where the user is located. |
| groupids `integer` | `Filters/Queries` `Orders`
The unique object identifiers of the groups the user is a member of. |
| roleids `integer` | `Filters/Queries` `Orders`
The unique object identifiers of the roles the user holds. |
| inactive `boolean` | `Filters/Queries` `Orders`
Indicates if the user is active. The user may set their personal preferences to always include inactive records.
***Note:*** The API response returns all users unless “isactive” is used in the request payload. The user interface, on the other hand, automatically filters to only return active users unless specifically requested to include inactive. The “isactive” field must be provided in the API request payload to receive the same results as the user interface by default. |
:::