# IRPCValueLists.SearchValueListItemsWithPermissions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md) > [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/

Badges: `Vault API / core` `read` `session or assertion` `idempotent` `returns metadata structure version`

Searches the items of one value list or object type by item ID, name, owner, parent or deleted
state.

- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-value-list-items-with-permissions`
- **Request:** [`SearchValueListItemsWithPermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md#request)
- **Response:** [`SearchValueListItemsWithPermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md#response)
- **Book and level:** Vault API, core
- **Kind:** read
- **Session:** Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
- **Idempotent:** yes
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session. No special vault rights are needed; items the user is not allowed
  to see are left out.
- Works for plain value lists and for real object types (whose items are objects). For the
  supported conditions, see the item search conditions table in the
  [IRPCValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) overview. Property values of objects cannot
  be searched here: use [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md).
- **Deleted items are included** by default and flagged with `item_info.options.is_deleted`.
  Add the condition Deleted (5) equal to false to get only existing items, or equal to true for
  only deleted ones. [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md) leaves
  deleted items out by default.
- `results_limit` 0 returns all matching items. With a limit, `has_more_results` tells whether
  more items matched; there is no paging.
- In hierarchical lists, the parents of matching items are returned too.
- With `include_permissions`, `item_acls` and `item_current_user_permissions` have one entry
  per item, in the order of `items`.
- The order of the items is not specified.
- An unknown list fails with "Not found.". Not cacheable.

<a id="request"></a>

## Request: SearchValueListItemsWithPermissionsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `call_importance` | [`CallImportance`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CallImportance/index.md) | The importance level of this call. Leave unset or use `CALL_IMPORTANCE_NORMAL`. Values: `CALL_IMPORTANCE_DEFAULT` (0), `CALL_IMPORTANCE_NORMAL` (1), `CALL_IMPORTANCE_CAN_BE_REJECTED` (2). |
| `external_data_source_refresh` | [`ExtDBRefreshType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtDBRefreshType/index.md) | For a list connected to an external database: whether to refresh it from the database before the search. `EXT_DBREFRESH_TYPE_NONE` reads the items the vault already has. Values: `EXT_DBREFRESH_TYPE_NONE` (0), `EXT_DBREFRESH_TYPE_QUICK` (1), `EXT_DBREFRESH_TYPE_FULL` (2). |
| `value_list` | `int32` | The ID of the value list or object type to search. |
| `filtering_property_def` | `int32` | The ID of a lookup property definition whose value filter (`PropertyDef.value_list_item_filter`) is applied, or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition ID (Name or title). |
| `search_conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | Conditions on the item pseudo properties 1-8 (see the service overview), combined with AND. Empty returns all items, deleted ones included. |
| `search_conditions[].expression` | [`Expression`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Expression/index.md) | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
| `search_conditions[].expression.type` | [`ExpressionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExpressionType/index.md) | The kind of expression. Must match the member set in `data`. Values: `EXPRESSION_TYPE_UNINITIALIZED` (0), `EXPRESSION_TYPE_PROPERTY_VALUE` (1), `EXPRESSION_TYPE_ID_SEGMENT` (2), `EXPRESSION_TYPE_STATUS_VALUE` (3), `EXPRESSION_TYPE_FILE_VALUE` (4), `EXPRESSION_TYPE_TYPED_VALUE` (5), `EXPRESSION_TYPE_ANY_FIELD` (6), `EXPRESSION_TYPE_PERMISSIONS` (7). |
| `search_conditions[].expression.data` | [`ExpressionUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExpressionUnion/index.md) | The expression data. Set the member that matches `type`. |
| `search_conditions[].expression.indirection_levels[]` | repeated [`IndirectionLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndirectionLevel/index.md) | The lookups to follow before evaluating the expression, from the searched object outwards. Empty evaluates the expression on the object itself. |
| `search_conditions[].type` | [`ConditionType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ConditionType/index.md) | The comparison operator. |
| `search_conditions[].value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for `STATUS_TYPE_IS_DELETED`. |
| `search_conditions[].value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `search_conditions[].value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `search_conditions[].value.data` | [`TypedValueUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnion/index.md) | The value, in the member that matches `type`. Unset for an empty value. |
| `resolve_current_user_placeholders` | `bool` | True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID. |
| `include_permissions` | `bool` | True to fill `item_acls` and `item_current_user_permissions`. |
| `results_limit` | `uint32` | The maximum number of items to return; 0 returns all. |

<a id="response"></a>

## Response: SearchValueListItemsWithPermissionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `items[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The matching items. See [ValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md). |
| `items[].item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item. |
| `items[].item_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object id or value list item id. Includes the object type or value list id. |
| `items[].item_info.name` | `string` | The name of the item. |
| `items[].item_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this item's external ID. Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5). |
| `items[].item_info.external_id` | `string` | The external ID (display ID) of this item. unset means that the external ID is the same as the internal ID. |
| `items[].item_info.guid` | `string` | GUID for the item. |
| `items[].item_info.options` | [`ITEMFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ITEMFLAGS/index.md) | Bit flags that provide additional information on the item (e.g. is the object deleted). |
| `items[].item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `items[].has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `items[].has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `items[].parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `items[].owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `items[].owner_name` | `string` | The name of the owner item. |
| `items[].automatic_permissions` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | If set, specifies the automatic permissions for an object for which the user selects this item. |
| `items[].automatic_permissions.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `items[].automatic_permissions.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `items[].automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `items[].icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains the icon of this item in .ICO format. |
| `items[].icon.value` | `bytes` | Array of bytes. |
| `item_acls[]` | repeated [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | With `include_permissions`, the access control list of each item, in the order of `items`; otherwise empty. |
| `item_acls[].checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `item_acls[].is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `item_acls[].custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `item_acls[].custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `item_acls[].custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `item_acls[].custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `item_acls[].custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `item_acls[].custom_component.permissions[]` | repeated [`AccessControlEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlEntry/index.md) | The access control entry datas. The data belongs to the key in the corresponding index. |
| `item_acls[].custom_component.overridability_permissions[]` | repeated [`AccessControlEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlEntry/index.md) | Overridability permission data of this ACL component. |
| `item_acls[].custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `item_acls[].restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `item_acls[].restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `item_acls[].restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `item_acls[].secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `item_acls[].additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `item_acls[].additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `item_acls[].additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `item_current_user_permissions[]` | repeated [`ObjectPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectPermissionsForClient/index.md) | With `include_permissions`, what the caller may do with each item, in the order of `items`; otherwise empty. |
| `item_current_user_permissions[].can_user_see` | `bool` | The object is visible for the current user (provided for symmetry). |
| `item_current_user_permissions[].can_user_edit` | `bool` | The current user can edit the object. |
| `item_current_user_permissions[].can_user_delete` | `bool` | The current user can delete the object. |
| `item_current_user_permissions[].can_user_change_permissions` | `bool` | The current user can change the object permissions. |
| `has_more_results` | `bool` | True if more items matched than `results_limit` allowed. |

<a id="related"></a>

## Related methods

- [IRPCSearch.SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md): Searches the vault for objects that match the given conditions.
- [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md): Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls.