Universal Lists

Programmatic access to the Bitrix24 Lists module: the lists themselves, their fields, sections, and elements.

Scope: lists | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

The module must be enabled separately on your Bitrix24 account. Universal Lists is a separate Bitrix24 module. If it is not activated on the account, calls return 409 LISTS_MODULE_NOT_ENABLED. This is not an integration error — ask the Bitrix24 account administrator to enable the Lists module and retry the request.

Data model

A list is an infoblock. Each call addresses data through three levels of keys.

Infoblock type — the iblockTypeId parameter. Possible values:

• lists — regular lists. The default value.
• lists_socnet — workgroup lists. They require socnetGroupId.
• bitrix_processes — internal workflows.
• structure — company-structure type. The stock absence-calendar infoblock (absence) lives here.

The type is passed in the query for GET and DELETE, and in the body for POST and PATCH.

List — the :iblockId path segment. A digits-only segment is the numeric IBLOCK_ID; a string is the symbolic code IBLOCK_CODE. Both forms are equivalent.

Field, section, or element — the corresponding nested path segment.

Responses are returned in Bitrix24 format. Keys are uppercase with underscores: ID, NAME, IBLOCK_TYPE_ID. Numeric identifiers are returned as strings, for example "ID": "121". Custom element properties are addressed by keys of the form PROPERTY_<id>. These keys are not converted to camelCase — some of them are dynamic.

Documentation sections

• Lists — creating, reading, updating, and deleting the lists themselves, plus the infoblock type.
• List fields — the set of list fields and a reference of allowed field types.
• Sections — grouping elements into sections with nesting support.
• Elements — list rows and file links from element properties.

Quick start

# All lists of type lists
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/lists?iblockTypeId=lists"

# Elements of list 23
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/lists/23/elements"

Full example

A five-step scenario: create a list, add a field, add an element with a value for that field, read the result, delete the list.

KEY="YOUR_API_KEY"
BASE="https://vibecode.bitrix24.com/v1"

# 1. Create the list → { "success": true, "data": { "id": 135 } }
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"iblockCode":"demo_orders","fields":{"NAME":"Demo: orders","SORT":100}}' \
  "$BASE/lists"

# 2. Add a field → { "success": true, "data": { "id": "PROPERTY_1179" } }
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"fields":{"NAME":"Status","TYPE":"S","CODE":"STATUS"}}' \
  "$BASE/lists/135/fields"

# 3. Add an element with a property value → { "success": true, "data": { "id": 7043 } }
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"elementCode":"row-1","fields":{"NAME":"Order #1","PROPERTY_1179":"new"}}' \
  "$BASE/lists/135/elements"

# 4. Read elements → data[0] = { "ID": "7043", "NAME": "Order #1", "PROPERTY_1179": { "3811": "new" } }
curl -s -H "X-Api-Key: $KEY" \
  "$BASE/lists/135/elements?select=ID,NAME,PROPERTY_1179"

# 5. Delete the list → HTTP 204 No Content (fields, sections, and elements are deleted along with it)
curl -s -X DELETE -H "X-Api-Key: $KEY" "$BASE/lists/135"

A field must be created with a CODE. A property value is passed as a string when creating ("PROPERTY_1179": "new"), and returned in the form { value_id: value } when reading.

Endpoint reference

Error codes

The full list of common API errors — Errors.

Limits

See also

• Lists
• List fields
• Sections
• Elements