# Value lists (IRPCValueLists)

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)

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

Reads value lists and their items, and lets users add and edit value list items and traditional
folders.

- **gRPC service:** `MFiles.IRPCValueLists`
- **Book and level:** [Vault API](https://developer.m-files.com/APIs/gRPC-API/vault/index.md), core
- **Methods:** 17
- **Proto file:** [`mfiles/IRPCValueLists.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCValueLists.proto)

<a id="overview"></a>

## Overview

Use it to fill lookup controls and to read or maintain the items of value lists. The service is
not read-only: the remarks of its write methods list the vault rights they need. For how value
lists relate to object types, classes and properties, see
[Vault and metadata structure](https://developer.m-files.com/APIs/gRPC-API/concepts/vault-and-metadata-structure/index.md);
for keeping a cached list current, see
[Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md).

- **List the value lists** (and object types) of the vault:
  [GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md),
  [GetValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueList/index.md).
- **Candidate values for lookup properties** (lookup control, autocomplete), several lists per
  call: [GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md).
- **Find items of one list** by name, ID, owner, parent or deleted state:
  [SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md).
- **Keep a local copy of a list** up to date with deltas:
  [GetValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md).
- **The user's recently used values** of a lookup property:
  [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md).
- **Add, update or undelete an item**:
  [AddValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md),
  [UpdateValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UpdateValueListItemFromClient/index.md),
  [UndeleteValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UndeleteValueListItem/index.md).
- **Traditional folders**:
  [CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md),
  [RenameValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RenameValueListItemFromClient/index.md),
  [RemoveValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveValueListItemFromClient/index.md),
  [RemoveOrDestroyTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md),
  [ChangeValueListItemPermissionsFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient/index.md).
- **Permissions of an item**:
  [GetValueListItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md),
  [CheckAccessToValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CheckAccessToValueListItem/index.md).

**IDs.** Value lists and object types share one ID space: an object type is a value list whose
items are objects (`ValueList.is_real_object_type`). The item calls accept both, so
[GetLookupItems](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetLookupItems/index.md) returns customers for object type
136 just as it returns countries for value list 154. An item is identified by an
[ObjID](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md): `type` is the value list ID and `item_id.internal_id` the item
ID. Item IDs are unique only within one list. Lookup property values
([PropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) with `is_based_on_value_list`) point to items of
`PropertyDef.value_list`. Built-in lists keep their IDs in every vault, for example 1 Classes,
2 Class groups, 4 Traditional folders, 6 Users, 7 Workflows, 8 Workflow states, 16 User groups.

**Item search conditions.** The `search_conditions` of the item searches are
[SearchCondition](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md)s whose expression is a property value
(`EXPRESSION_TYPE_PROPERTY_VALUE`) on one of these pseudo property definition IDs. They exist
only in item searches; ordinary property definitions are rejected with "Invalid search
condition.". Conditions are combined with AND.

| ID | Item field | Value (`TypedValue`) | Example condition type |
| --- | --- | --- | --- |
| 1 | Item ID | `DATATYPE_INTEGER` | `CONDITION_TYPE_EQUAL` |
| 2 | Name | `DATATYPE_TEXT` | `CONDITION_TYPE_CONTAINS`, `CONDITION_TYPE_STARTS_WITH` (case-insensitive) |
| 3 | Owner item | `DATATYPE_LOOKUP` (`lookup.value_list_item_info.obj_id` = owner item) | `CONDITION_TYPE_EQUAL` |
| 4 | Parent item | `DATATYPE_INTEGER`, or unset for top-level items | `CONDITION_TYPE_EQUAL` |
| 5 | Deleted | `DATATYPE_BOOLEAN` | `CONDITION_TYPE_EQUAL` |
| 6 | Object type | `DATATYPE_INTEGER` | `CONDITION_TYPE_EQUAL` |
| 7 | External (display) ID | `DATATYPE_TEXT` | `CONDITION_TYPE_EQUAL` |
| 8 | GUID | `DATATYPE_TEXT` (with braces) | `CONDITION_TYPE_EQUAL` |

To search objects by their properties, use [SearchObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCSearch/SearchObjects/index.md)
instead. Item lists are not covered by the metadata structure version: adding or changing items does not
change the `mfiles-metadata-version-bin` trailer, so do not cache items by it.

<a id="highlighted"></a>

## Highlighted methods

| Method | Summary | Facts |
|---|---|---|
| [GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md) | Gets all value lists of the vault, including the object types, without icons. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [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. | `write` `session or assertion` `returns metadata structure version` |
| [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. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md) | Searches the items of one value list or object type by item ID, name, owner, parent or deleted state. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [AddValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md) | Adds a new item to a value list, as a user. | `write` `session or assertion` `returns metadata structure version` |

<a id="methods"></a>

## Other methods

| Method | Summary | Facts |
|---|---|---|
| [ChangeValueListItemPermissionsFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/ChangeValueListItemPermissionsFromClient/index.md) | Changes the permissions of a traditional folder. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [CheckAccessToValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CheckAccessToValueListItem/index.md) | Checks whether the calling user has the given access under an access control list that the caller supplies. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [CreateFolderTree](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateFolderTree/index.md) | Creates a tree of traditional folders under one anchor in one transaction: either every folder is created or the call fails and nothing is saved. | `write` `session or assertion` `returns metadata structure version` |
| [CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md) | Creates a traditional folder, or returns an existing folder with the same name. | `write` `session or assertion` `returns metadata structure version` |
| [GetValueListItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemPermissions/index.md) | Gets the permissions of one item of a plain value list. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetValueListItemProposals](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemProposals/index.md) | Gets the values that the calling user has most recently used for a lookup property. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [GetValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueListItemsWithPermissions/index.md) | Gets the items of one value list or object type, or only the changes since a known version. | `read` `session or assertion` `idempotent` `returns metadata structure version` |
| [RemoveOrDestroyTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveOrDestroyTraditionalFolder/index.md) | Deletes or destroys a traditional folder and everything in it. | `write` `session or assertion` `returns metadata structure version` |
| [RemoveValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RemoveValueListItemFromClient/index.md) | Deletes a traditional folder (marks it deleted). | `write` `session or assertion` `returns metadata structure version` |
| [RenameValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/RenameValueListItemFromClient/index.md) | Renames a traditional folder. | `write` `session or assertion` `idempotent` `returns metadata structure version` |
| [UndeleteValueListItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UndeleteValueListItem/index.md) | Restores a deleted item of a plain value list, together with its deleted parent items. | `write` `session or assertion` |
| [UpdateValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/UpdateValueListItemFromClient/index.md) | Updates an item of a plain value list or a traditional folder, as a user. | `write` `session or assertion` `returns metadata structure version` |