# IRPCValueLists.GetValueListItemsWithPermissions

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/GetValueListItemsWithPermissions/

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

Gets the items of one value list or object type, or only the changes since a known version.

- **Service:** [Value lists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) `MFiles.IRPCValueLists`
- **gRPC method:** `/MFiles.IRPCValueLists/GetValueListItemsWithPermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-value-list-items-with-permissions`
- **Request:** [`GetValueListItemsWithPermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md#request)
- **Response:** [`GetValueListItemsWithPermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/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 cannot see are
  left out. Deleted items are not returned (except as `removed_items` in a delta).
- Meant for clients that keep a local copy of a list. First call with `known_version` 0 and
  store `current_version`. Later, send it back as `known_version` with `allow_delta`:
  - unchanged list: same `current_version`, no items;
  - changed list: `is_delta` true, `items` has the added and changed items and `removed_items`
    the IDs of deleted ones;
  - if the server cannot give a delta, `is_delta` is false and `items` is the full list.
- The server limits the number of items (`results_limit` in the response, 5000 by default);
  `has_more_results` tells whether the list was cut. For large lists use
  [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md) with a name condition.

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

## Request: GetValueListItemsWithPermissionsRequest

> 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 first. 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. |
| `filtering_property_def` | `int32` | The ID of a lookup property definition whose value filter is applied, or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition. |
| `known_version` | `int64` | The `current_version` from the caller's previous response, or 0 to get the full list. With 0 the server never returns a delta. |
| `allow_delta` | `bool` | True to accept only the changes since `known_version`. |
| `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`. |

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

## Response: GetValueListItemsWithPermissionsResponse

> 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 |
|---|---|---|
| `current_version` | `int64` | The current version of the list's items. Store it and send it as `known_version` next time. It changes when items change, not with the metadata structure version. |
| `is_delta` | `bool` | True if `items` and `removed_items` are only the changes since `known_version`. |
| `removed_items[]` | repeated `int32` | In a delta, the IDs of items deleted since `known_version`; otherwise empty. |
| `items[]` | repeated [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The items, or in a delta the added and changed items. |
| `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`. |
| `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`. |
| `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 the list has more items than `results_limit`. |
| `results_limit` | `uint32` | The item limit the server applied (0 when no items were returned). |

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

## Related methods

- [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.
- [GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md): Gets one value list or object type by ID, without its icon.