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

List fields

Manage a list's field set: get field descriptions, create new fields, update and delete them. A separate operation returns the reference of allowed field types.

Bitrix24 API: lists.field.* Scope: lists

List fields

GET /v1/lists/:iblockId/fields

Returns descriptions of all list fields — system and user. For each field it returns the type, whether the field is required, whether it allows multiple values, and form display settings.

Parameters

Parameter Type Req. Description
iblockId (path) string yes List identifier. Numeric IBLOCK_ID or symbolic IBLOCK_CODE. List — GET /v1/lists
iblockTypeId (query) string no Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/lists/121/fields \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/lists/121/fields \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/121/fields', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Field IDs:', Object.keys(data))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/121/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

The data field is a dictionary object. The top-level key is the field identifier FIELD_ID, the value is that field's description. The description keys are listed below.

Field Type Description
success boolean Always true on success
data object Field dictionary, key — FIELD_ID, value — field description
data.<FIELD_ID>.FIELD_ID string Field identifier. For user fields — PROPERTY_<number>, for system fields — a symbolic code, for example NAME
data.<FIELD_ID>.NAME string Display name of the field
data.<FIELD_ID>.TYPE string Field type code. Code reference — Field types
data.<FIELD_ID>.IS_REQUIRED string Whether the field is required: Y or N
data.<FIELD_ID>.MULTIPLE string Allows multiple values: Y or N
data.<FIELD_ID>.SORT number Sort order in the form
data.<FIELD_ID>.DEFAULT_VALUE string or null Default value
data.<FIELD_ID>.CODE string or null Symbolic code of the field. Present only for user fields
data.<FIELD_ID>.ID string Numeric identifier of a user field as a string. Absent for system fields
data.<FIELD_ID>.PROPERTY_TYPE string or boolean Base type of a user field. For system fields it returns false
data.<FIELD_ID>.SETTINGS object or boolean Field display settings in forms. For system fields it returns false
data.<FIELD_ID>.IBLOCK_ID number Identifier of the list the field belongs to

User fields additionally contain:

  • PROPERTY_USER_TYPE — extended type of the user property, for example a CRM binding, date, or money. For system fields it returns false.
  • LINK_IBLOCK_ID — identifier of the linked list for binding properties. null if the field does not reference another list.
  • ROW_COUNT — height of the input field in the form, in rows.
  • COL_COUNT — width of the input field in the form, in characters.
  • USER_TYPE_SETTINGS — additional settings of the user property type. null if there are none.

Element binding fields additionally return DISPLAY_VALUES_FORM — a map of linked element identifiers and their names.

Response example

JSON 
{
  "success": true,
  "data": {
    "NAME": {
      "FIELD_ID": "NAME",
      "SORT": 20,
      "NAME": "Name",
      "IS_REQUIRED": "Y",
      "MULTIPLE": "N",
      "DEFAULT_VALUE": "",
      "TYPE": "NAME",
      "PROPERTY_TYPE": false,
      "PROPERTY_USER_TYPE": false,
      "SETTINGS": false,
      "IBLOCK_ID": 121
    },
    "PROPERTY_1149": {
      "FIELD_ID": "PROPERTY_1149",
      "SORT": 10,
      "NAME": "Priority",
      "IS_REQUIRED": "N",
      "MULTIPLE": "N",
      "DEFAULT_VALUE": "0",
      "TYPE": "N",
      "PROPERTY_TYPE": "N",
      "PROPERTY_USER_TYPE": false,
      "CODE": "PRIORITY",
      "ID": "1149",
      "LINK_IBLOCK_ID": null,
      "ROW_COUNT": "1",
      "COL_COUNT": "30",
      "USER_TYPE_SETTINGS": null,
      "SETTINGS": {
        "SHOW_ADD_FORM": "Y",
        "SHOW_EDIT_FORM": "Y",
        "ADD_READ_ONLY_FIELD": "N",
        "EDIT_READ_ONLY_FIELD": "N",
        "SHOW_FIELD_PREVIEW": "N"
      },
      "IBLOCK_ID": 121
    }
  }
}

Error response example

403 — no permissions for the list, or no list with such an identifier exists:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "No permission to view or edit the list."
  }
}

Errors

HTTP Code Description
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of the allowed types
403 BITRIX_ACCESS_DENIED No permission to view the list, or a list with the given identifier does not exist
403 SCOPE_DENIED The key is missing 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

Fields are returned as an object, not an array. The top-level key is the field identifier FIELD_ID. To iterate over all fields, use Object.values(data) or Object.keys(data). SORT sets the display order in the form.

See also