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

Get field

GET /v1/lists/:iblockId/fields/:fieldId

Returns the description of a single list field by its identifier. Useful when you need the parameters of a specific field rather than the whole set.

Parameters

Parameter Type Req. Description
iblockId (path) string yes List identifier. Numeric IBLOCK_ID or symbolic IBLOCK_CODE. List — GET /v1/lists
fieldId (path) string yes Field identifier. For user fields — PROPERTY_<number>, for system fields — a symbolic code, for example NAME. Values — in List fields, key FIELD_ID
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/PROPERTY_1149 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/lists/121/fields/PROPERTY_1149 \
  -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/PROPERTY_1149', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
const field = Object.values(data)[0]
console.log('Field:', field.NAME)

JavaScript — OAuth application

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

Response fields

The data field is an object with a single key. The key is the field type code, the value is the field description. The description keys are listed below.

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

Response example

JSON 
{
  "success": true,
  "data": {
    "S": {
      "FIELD_ID": "PROPERTY_1149",
      "SORT": 10,
      "NAME": "Status",
      "IS_REQUIRED": "N",
      "MULTIPLE": "N",
      "DEFAULT_VALUE": null,
      "TYPE": "S",
      "PROPERTY_TYPE": "S",
      "PROPERTY_USER_TYPE": false,
      "CODE": "STATUS",
      "ID": "1149",
      "LINK_IBLOCK_ID": null,
      "ROW_COUNT": "1",
      "COL_COUNT": "30",
      "USER_TYPE_SETTINGS": null,
      "SETTINGS": false
    }
  }
}

Error response example

404 — field not found:

JSON 
{
  "success": false,
  "error": {
    "code": "FIELD_NOT_FOUND",
    "message": "Field not found"
  }
}

Errors

HTTP Code Description
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of the allowed types
404 FIELD_NOT_FOUND No field with the given fieldId exists in the list
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

The top-level key in the response is the field type code, not FIELD_ID. In the List fields operation the top-level key is the field identifier FIELD_ID, whereas here it is the field type code, for example S. The identifier itself is passed in the path and is repeated inside the description in data.<TYPE>.FIELD_ID. To get the description, take the first value of the object: Object.values(data)[0].

See also