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
ParameteriblockId (path) Typestring Requiredyes DescriptionList ID or symbolic code. Use ID or CODE from the List lists response
ParameterfieldId (path) Typestring Requiredyes DescriptionThe 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
FieldiblockTypeId Typestring Requiredno DescriptionInfo 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)
FieldsocnetGroupId Typenumber Requiredno DescriptionWorkgroup ID for lists of type lists_socnet. A positive integer from the id field returned by List workgroups
Fieldfields Typeobject Requiredyes DescriptionField properties in Bitrix24 format. Property names are uppercase. Pass NAME, the current TYPE, and the properties to change
Fieldfields.TYPE Typestring Requiredyes DescriptionCurrent type from the TYPE field returned by Get a field. Required with every update, but cannot be changed. For code descriptions, see Field types
Fieldfields.NAME Typestring Requiredyes DescriptionField name. Pass the current name to leave it unchanged
Fieldfields.IS_REQUIRED Typestring Requiredno DescriptionWhether the field is required: Y or N
Fieldfields.MULTIPLE Typestring Requiredno DescriptionWhether the field allows multiple values: Y or N
Fieldfields.SORT Typenumber Requiredno DescriptionField 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
Fieldfields.DEFAULT_VALUE Typestring or object Requiredno DescriptionDefault value. The format depends on TYPE: a string for S, or an object with TYPE and TEXT keys for S:HTML
Fieldfields.CODE Typestring Requiredno DescriptionSymbolic code of a custom field. Use FIELD_ID in the request path, not this code
Fieldfields.ROW_COUNT Typenumber Requiredno DescriptionInput height in rows
Fieldfields.COL_COUNT Typenumber Requiredno DescriptionInput width in characters
Fieldfields.LINK_IBLOCK_ID Typenumber Requiredno DescriptionLinked list ID for reference types G, E, and E:.... Use the ID field returned by List lists
Fieldfields.USER_TYPE_SETTINGS Typeobject Requiredno DescriptionSettings for an extended property type. The available settings depend on TYPE. For current settings, see USER_TYPE_SETTINGS in Get a field
Fieldfields.LIST Typeobject Requiredno DescriptionOptions 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
Fieldfields.LIST.<ID>.VALUE Typestring Requiredyes DescriptionOption text
Fieldfields.LIST.<ID>.SORT Typenumber Requiredno DescriptionOption sort order
Fieldfields.LIST.<ID>.DEF Typestring Requiredno DescriptionWhether the option is selected by default: Y or N
Fieldfields.LIST_TEXT_VALUES Typestring Requiredno DescriptionNew options for a field of type L, one per line. Use \n as the separator. Can be passed together with LIST
Fieldfields.LIST_DEF Typestring[] Requiredno DescriptionIDs 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
Fieldfields.SETTINGS Typeobject Requiredno DescriptionField display settings. To preserve other settings in this object, pass them together with the changed settings
Fieldfields.SETTINGS.SHOW_ADD_FORM Typestring Requiredno DescriptionShow the field when adding an item: Y or N
Fieldfields.SETTINGS.SHOW_EDIT_FORM Typestring Requiredno DescriptionShow the field when editing an item: Y or N
Fieldfields.SETTINGS.ADD_READ_ONLY_FIELD Typestring Requiredno DescriptionMake the field read-only when adding an item: Y or N. Set a default value when using Y
Fieldfields.SETTINGS.EDIT_READ_ONLY_FIELD Typestring Requiredno DescriptionMake the field read-only when editing an item: Y or N
Fieldfields.SETTINGS.SHOW_FIELD_PREVIEW Typestring Requiredno DescriptionShow 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionField update result
Fielddata.updated Typeboolean Descriptiontrue on a successful update

Response example

HTTP 200 OK:

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

Error response example

422 — TYPE is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required parameter \"TYPE\" is missing",
    "b24Code": "ERROR_REQUIRED_PARAMETERS_MISSING"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not one of lists, bitrix_processes, lists_socnet, structure
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe fields object is missing
HTTP422 CodeBITRIX_ERROR DescriptionNAME or TYPE is missing. The b24Code field is ERROR_REQUIRED_PARAMETERS_MISSING
HTTP422 CodeBITRIX_ERROR DescriptionAn attempt to change the field type. The b24Code field is ERROR_UPDATE_FIELD
HTTP422 CodeBITRIX_ERROR DescriptionNo field with the specified fieldId was found. The b24Code field is ERROR_UPDATE_FIELD
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo permission to edit the list
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the lists scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP409 CodeLISTS_MODULE_NOT_ENABLED DescriptionThe Lists module is not enabled on the portal

For the full list of common API errors, see Errors.

Known specifics

The fields.ID value is ignored. The field to update is determined by the fieldId parameter in the request path.

See also