# IRPCValueLists.AddValueListItemFromClient

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

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

Adds a new item to a value list, as a user.

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

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

## Remarks

- Requires a vault session whose user has the vault rights `manage_value_list_items_from_client`
  and `license_allows_modifications` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); otherwise the
  call fails with "Access denied.".
- The list must allow new items (`ValueList.options.can_add_items`), and the user must be
  allowed to add items to it (`ValueList.object_type_permissions.can_user_add_new_items`).
  Otherwise the call fails with "Access denied." or "You are not allowed to add new values to
  the list ...".
- Only plain value lists: a real object type fails with "Not found." (create objects with
  [AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md)), and Traditional folders (4) fail
  with "The parameter is incorrect." (use
  [CreateOrFindTraditionalFolder](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder/index.md)).
- The name must not be empty. `has_parent` is allowed only in hierarchical lists and
  `has_owner` only in lists that are not hierarchical; violations fail with an error.
- The server assigns the item ID and a new GUID; the values you send are ignored. Names do not
  have to be unique, so a retried call creates a second item with the same name: search by name
  first if the call may be repeated.
- The new item gets the list's default permissions for new items. If the user could not see the
  new item, the call fails and nothing is added.
- For a list connected to an external database, the item is also written to that database.
  Vault event handlers for new value list items run.
- Adding items does not change the metadata structure version. Remove items with the administration
  service ([RemoveObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md));
  this service cannot remove items of ordinary value lists.

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

## Request: AddValueListItemFromClientRequest

> 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 |
|---|---|---|
| `utf8szvlitem` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The item to add. Set `item_info.obj_id.type` to the value list ID and `item_info.name`; for a hierarchical list set `has_parent` and `parent_id`, for a list with an owner list set `has_owner` and `owner_id`. The item ID and GUID are ignored. |
| `utf8szvlitem.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. |
| `utf8szvlitem.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. |
| `utf8szvlitem.item_info.name` | `string` | The name of the item. |
| `utf8szvlitem.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). |
| `utf8szvlitem.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. |
| `utf8szvlitem.item_info.guid` | `string` | GUID for the item. |
| `utf8szvlitem.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). |
| `utf8szvlitem.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `utf8szvlitem.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `utf8szvlitem.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `utf8szvlitem.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `utf8szvlitem.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `utf8szvlitem.owner_name` | `string` | The name of the owner item. |
| `utf8szvlitem.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. |
| `utf8szvlitem.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. |
| `utf8szvlitem.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. |
| `utf8szvlitem.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `utf8szvlitem.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. |
| `utf8szvlitem.icon.value` | `bytes` | Array of bytes. |

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

## Response: AddValueListItemFromClientResponse

> 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 |
|---|---|---|
| `result` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The new item as stored, with its new item ID and GUID. |
| `result.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. |
| `result.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. |
| `result.item_info.name` | `string` | The name of the item. |
| `result.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). |
| `result.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. |
| `result.item_info.guid` | `string` | GUID for the item. |
| `result.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). |
| `result.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `result.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `result.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `result.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `result.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `result.owner_name` | `string` | The name of the owner item. |
| `result.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. |
| `result.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. |
| `result.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. |
| `result.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `result.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. |
| `result.icon.value` | `bytes` | Array of bytes. |

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

## Related methods

- [IRPCObjectOperations.AddObject](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/AddObject/index.md): Creates a new object without files.
- [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.
- [IRPCObjectTypesAdmin.RemoveObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md): Deletes an item of a value list as an administrator.