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

Untuk ejen AI: markdown halaman ini — /docs-content-en/lists/elements.md indeks dokumentasi — /llms.txt

Artikel dokumentasi kini tersedia dalam bahasa Inggeris.

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 pagination.

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 (holds the built-in 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%"}. Important: 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: parsing such a query string would irrecoverably drop half of the conditions. An empty ?filter= means "no filter". A field that cannot be filtered on is rejected with 422 BITRIX_ERROR. A filter on ACTIVE is accepted and applied: a value other than Y or N returns an empty array.
select (query) string no — Comma-separated list of returned fields. A custom property is requested as PROPERTY_<id>. Example: ?select=ID,NAME,PROPERTY_1149. A name the list does not return causes no error: that field is simply absent from the response. ID is always returned, even when it is not in select
start (query) number no 0 Offset from the start of the result set, for pagination
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

The set of fields in the response is not fixed: some fields named in select may not come back, and elements of the same list carry different sets of keys. A missing field means neither an empty value nor N. The activity flag ACTIVE is not returned, with or without select. To get only active elements, filter with ?filter={"ACTIVE":"Y"}.

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 shape is described 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 shape 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
422 BITRIX_ERROR filter names a field that cannot be filtered on. The error text names the field: Filter field not allowed: <field>
403 BITRIX_ACCESS_DENIED No access to the list. As measured on 2026-09-02, a list that does not exist at this address returns 404, but Bitrix24 also returns this code when permissions 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

For the full list of common API errors, see Errors.

Known specifics

Custom property values arrive under PROPERTY_<id> keys as a map from value identifier to value. The same shape is shown in detail in Get element.

See also