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

Para agentes de IA: markdown desta página — /docs-content-en/lists/elements.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

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
structure — company-structure type (absence-calendar iblock absence)
filter (query) string no — JSON filter object over element fields. Key is the field name, value is the condition. Example: ?filter={"NAME":"%report%"} ⚠️ Pass the WHOLE filter in a single form — either bracket notation or one JSON object. A mixed envelope (?filter[NAME]=x&filter=) and a bracket condition deeper than two levels are rejected with 400 INVALID_FILTER: half of the conditions are irrecoverably lost while the query string is parsed. An empty ?filter= means "no filter".
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 AND the value is greater than zero — zero addresses the same first page as no offset at all

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, structure
400 INVALID_FILTER The filter parameter is not valid JSON An ambiguous envelope is rejected as well: the bracket form and JSON in one request (in either order), two spellings of one condition, or a bracket condition deeper than two levels — half of the conditions are irrecoverably lost during parsing, so the request is refused rather than half-applied.
400 INVALID_PARAMS start or offset is not a non-negative integer. Such a value used to be dropped silently, and the page served was not the one asked for
403 BITRIX_ACCESS_DENIED No access to the list. On this address an absent list was measured (2026-09-02) to answer 404 — but Bitrix24 also answers here when the rights are genuinely missing
404 LIST_NOT_FOUND No list with the given iblockId exists. Bitrix24 reports this with a machine code, so an absent list is distinguishable from a permission refusal
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