For AI agents: markdown of this page — /docs-content-en/lists/fields/update.md documentation index — /llms.txt

Update a field

PATCH /v1/lists/:iblockId/fields/:fieldId

Changes the properties of an existing list field. Pass new values in the fields object using the Bitrix24 format.

Parameters

Parameter	Type	Required	Description
`iblockId` (path)	string	yes	List ID or symbolic code. Use `ID` or `CODE` from the List lists response
`fieldId` (path)	string	yes	The `FIELD_ID` value from the List fields response. Custom fields use `PROPERTY_<number>`. System fields use a symbolic code, such as `NAME`

Request fields (body)

The main settings are the name (fields.NAME), whether the field is required (fields.IS_REQUIRED), and its position (fields.SORT). Pass the current fields.TYPE with every update.

Field	Type	Required	Description
`iblockTypeId`	string	no	Info block type. Values: `lists` — regular lists, the default `lists_socnet` — workgroup lists `bitrix_processes` — service workflows `structure` — company structure type (contains the built-in absence calendar info block `absence`)
`socnetGroupId`	number	no	Workgroup ID for lists of type `lists_socnet`. A positive integer from the `id` field returned by List workgroups
`fields`	object	yes	Field properties in Bitrix24 format. Property names are uppercase. Pass `NAME`, the current `TYPE`, and the properties to change
`fields.TYPE`	string	yes	Current type from the `TYPE` field returned by Get a field. Required with every update, but cannot be changed. For code descriptions, see Field types
`fields.NAME`	string	yes	Field name. Pass the current name to leave it unchanged
`fields.IS_REQUIRED`	string	no	Whether the field is required: `Y` or `N`
`fields.MULTIPLE`	string	no	Whether the field allows multiple values: `Y` or `N`
`fields.SORT`	number	no	Field position in the form. To preserve the order, pass the current `SORT` value from Get a field. Without `SORT`, the field may move to the beginning. Sort values are recalculated in increments of 10 after the update
`fields.DEFAULT_VALUE`	string or object	no	Default value. The format depends on `TYPE`: a string for `S`, or an object with `TYPE` and `TEXT` keys for `S:HTML`
`fields.CODE`	string	no	Symbolic code of a custom field. Use `FIELD_ID` in the request path, not this code
`fields.ROW_COUNT`	number	no	Input height in rows
`fields.COL_COUNT`	number	no	Input width in characters
`fields.LINK_IBLOCK_ID`	number	no	Linked list ID for reference types `G`, `E`, and `E:...`. Use the `ID` field returned by List lists
`fields.USER_TYPE_SETTINGS`	object	no	Settings for an extended property type. The available settings depend on `TYPE`. For current settings, see `USER_TYPE_SETTINGS` in Get a field
`fields.LIST`	object	no	Options for a field of type `L`. Each key is an option ID from `DISPLAY_VALUES_FORM` in Get a field. Each value is an object with the properties listed below
`fields.LIST.<ID>.VALUE`	string	yes	Option text
`fields.LIST.<ID>.SORT`	number	no	Option sort order
`fields.LIST.<ID>.DEF`	string	no	Whether the option is selected by default: `Y` or `N`
`fields.LIST_TEXT_VALUES`	string	no	New options for a field of type `L`, one per line. Use `\n` as the separator. Can be passed together with `LIST`
`fields.LIST_DEF`	string[]	no	IDs of default options for a field of type `L`. Use the keys of `DISPLAY_VALUES_FORM` from Get a field. Include these options in `LIST` as well
`fields.SETTINGS`	object	no	Field display settings. To preserve other settings in this object, pass them together with the changed settings
`fields.SETTINGS.SHOW_ADD_FORM`	string	no	Show the field when adding an item: `Y` or `N`
`fields.SETTINGS.SHOW_EDIT_FORM`	string	no	Show the field when editing an item: `Y` or `N`
`fields.SETTINGS.ADD_READ_ONLY_FIELD`	string	no	Make the field read-only when adding an item: `Y` or `N`. Set a default value when using `Y`
`fields.SETTINGS.EDIT_READ_ONLY_FIELD`	string	no	Make the field read-only when editing an item: `Y` or `N`
`fields.SETTINGS.SHOW_FIELD_PREVIEW`	string	no	Show the field in the item preview: `Y` or `N`

Examples

curl — personal key

Terminal

curl -X PATCH https://vibecode.bitrix24.com/v1/lists/23/fields/PROPERTY_1177 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "Current status",
      "TYPE": "S",
      "SORT": 10
    }
  }'

curl — OAuth application

Terminal

curl -X PATCH https://vibecode.bitrix24.com/v1/lists/23/fields/PROPERTY_1177 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "NAME": "Current status",
      "TYPE": "S",
      "SORT": 10
    }
  }'

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/fields/PROPERTY_1177', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'Current status',
      TYPE: 'S',
      SORT: 10,
    },
  }),
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/fields/PROPERTY_1177', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      NAME: 'Current status',
      TYPE: 'S',
      SORT: 10,
    },
  }),
})

Response fields

Field	Type	Description
`success`	boolean	Always `true` on success
`data`	object	Field update result
`data.updated`	boolean	`true` on a successful update

Response example

HTTP 200 OK:

JSON

{
  "success": true,
  "data": {
    "updated": true
  }
}

Error response example

422 — TYPE is missing: