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. New values are passed in the fields object in Bitrix24 form.

Parameters

Parameter Type Required Description
iblockId (path) string yes List identifier — numeric IBLOCK_ID or symbolic IBLOCK_CODE. List of lists: GET /v1/lists
fieldId (path) string yes Field identifier in the form PROPERTY_<number> or symbolic code. List of fields: GET /v1/lists/:iblockId/fields

Request fields (body)

Field Type Required Description
iblockTypeId string no Info block type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows
fields object yes The field properties to change in Bitrix24 form (uppercase)
fields.TYPE string yes The field's current type. Passed on every update but not changed
fields.NAME string no New field name
fields.IS_REQUIRED string no Whether the field is required: Y or N
fields.MULTIPLE string no Multiple value: Y or N
fields.SORT number no Field sort index in the card
fields.DEFAULT_VALUE string no Default value

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"
    }
  }'

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"
    }
  }'

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',
    },
  }),
})

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',
    },
  }),
})

Response fields

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

Response example

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

Error response example

422 — TYPE not passed:

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

Errors

HTTP Code Description
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of lists, bitrix_processes, lists_socnet
400 MISSING_REQUIRED_FIELDS The fields object is missing
422 BITRIX_ERROR Bitrix24 rejected the update. For example, TYPE is not passed — message «Required parameter "TYPE" is missing»
403 BITRIX_ACCESS_DENIED No permission to edit the list
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
403 SCOPE_DENIED The key lacks the lists scope
401 TOKEN_MISSING The key has no configured tokens
409 LISTS_MODULE_NOT_ENABLED The «Lists» module is not enabled on the portal

Full list of common API errors — Errors.

Known specifics

The field type is specified but not changed. The fields.TYPE field is required in the update body — without it the request ends with a 422 BITRIX_ERROR response and the message «Required parameter "TYPE" is missing». Pass the current field type. You cannot change the type of an already created field through this endpoint.

See also