keys."> keys."> keys.">

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

Elements

Work with list rows: retrieve elements with filtering, create, update, and delete them, and get links to files from element properties. Custom property values are addressed by PROPERTY_<id> keys.

Bitrix24 API: lists.element.* Scope: lists

List elements

GET /v1/lists/:iblockId/elements

Returns list elements with filtering and paginated traversal.

Parameters

Parameter Type Required Default Description
iblockId (path) string yes — Numeric list identifier IBLOCK_ID or symbolic code IBLOCK_CODE
iblockTypeId (query) string no lists Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows
filter (query) string no — JSON filter object over element fields. Key is the field name, value is the condition. Example: ?filter={"NAME":"%report%"}
select (query) string no — Comma-separated list of returned fields. A custom property is requested as PROPERTY_<id>. Example: ?select=ID,NAME,PROPERTY_1149
start (query) number no 0 Offset from the start of the selection for paginated traversal
offset (query) number no 0 Alias of start. Applied when start is not passed

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/lists/121/elements \
  -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/elements', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()
console.log(`Elements: ${meta.total}`, data)

JavaScript — OAuth application

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of list elements
data[].ID string Element identifier
data[].NAME string Element name
data[].IBLOCK_SECTION_ID string or null Section identifier, null for an element outside sections
data[].PROPERTY_<id> object Custom property values. Key is the property identifier from List fields. The value form is in the "Known specifics" section
meta.total number Total number of elements matching the filter

Response example

System fields are shown. Custom properties are returned under PROPERTY_<id> keys — their form is shown in Get element.

JSON 
{
  "success": true,
  "data": [
    { "ID": "501", "NAME": "Sample element", "IBLOCK_SECTION_ID": null },
    { "ID": "502", "NAME": "Draft", "IBLOCK_SECTION_ID": "12" }
  ],
  "meta": { "total": 2 }
}

Error response example

403 — no access to the list:

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

Errors

HTTP Code Description
400 INVALID_IBLOCK_TYPE iblockTypeId is not in the set lists, bitrix_processes, lists_socnet
400 INVALID_FILTER The filter parameter is not valid JSON
403 BITRIX_ACCESS_DENIED No access to the list, or a list with the given iblockId does not exist
409 LISTS_MODULE_NOT_ENABLED The "Lists" module is not enabled on the portal
403 SCOPE_DENIED The key lacks the lists scope
401 TOKEN_MISSING The key has no access tokens configured

The full list of common API errors — Errors.

Known specifics

Custom property values arrive under PROPERTY_<id> keys as a mapping "value identifier — value". The same form is shown in detail in Get element.

See also