# 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 is 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.

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

**List** — the `:iblockId` path segment. Digits only mean the numeric `IBLOCK_ID`, a string means the symbolic code `IBLOCK_CODE`. Both options 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](/docs/lists/lists) — creating, reading, updating, and deleting the lists themselves, plus the infoblock type.
- [List fields](/docs/lists/fields) — the set of list fields and a reference of allowed field types.
- [Sections](/docs/lists/sections) — grouping elements into sections with nesting support.
- [Elements](/docs/lists/elements) — list rows and file links from element properties.

## Quick start

```bash
# 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.

```bash
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 is created with a required `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

| Method | Path | Bitrix24 method | Description |
|-------|------|----------------|----------|
| GET | [`/v1/lists`](/docs/lists/lists/list) | lists.get | Lists of the given type |
| POST | [`/v1/lists`](/docs/lists/lists/create) | lists.add | Create a list |
| GET | [`/v1/lists/:iblockId`](/docs/lists/lists/get) | lists.get | A single list |
| PATCH | [`/v1/lists/:iblockId`](/docs/lists/lists/update) | lists.update | Update a list |
| DELETE | [`/v1/lists/:iblockId`](/docs/lists/lists/delete) | lists.delete | Delete a list |
| GET | [`/v1/lists/:iblockId/type`](/docs/lists/lists/type) | lists.get.iblock.type.id | Infoblock type by id or code |
| GET | [`/v1/lists/:iblockId/fields`](/docs/lists/fields/list) | lists.field.get | All list fields |
| GET | [`/v1/lists/:iblockId/fields/:fieldId`](/docs/lists/fields/get) | lists.field.get | A single field |
| POST | [`/v1/lists/:iblockId/fields`](/docs/lists/fields/create) | lists.field.add | Create a field |
| PATCH | [`/v1/lists/:iblockId/fields/:fieldId`](/docs/lists/fields/update) | lists.field.update | Update a field |
| DELETE | [`/v1/lists/:iblockId/fields/:fieldId`](/docs/lists/fields/delete) | lists.field.delete | Delete a field |
| GET | [`/v1/lists/:iblockId/field-types`](/docs/lists/fields/field-types) | lists.field.type.get | Field type reference |
| GET | [`/v1/lists/:iblockId/sections`](/docs/lists/sections/list) | lists.section.get | List sections |
| GET | [`/v1/lists/:iblockId/sections/:sectionId`](/docs/lists/sections/get) | lists.section.get | A single section |
| POST | [`/v1/lists/:iblockId/sections`](/docs/lists/sections/create) | lists.section.add | Create a section |
| PATCH | [`/v1/lists/:iblockId/sections/:sectionId`](/docs/lists/sections/update) | lists.section.update | Update a section |
| DELETE | [`/v1/lists/:iblockId/sections/:sectionId`](/docs/lists/sections/delete) | lists.section.delete | Delete a section |
| GET | [`/v1/lists/:iblockId/elements`](/docs/lists/elements/list) | lists.element.get | List elements |
| GET | [`/v1/lists/:iblockId/elements/:elementId`](/docs/lists/elements/get) | lists.element.get | A single element |
| POST | [`/v1/lists/:iblockId/elements`](/docs/lists/elements/create) | lists.element.add | Create an element |
| PATCH | [`/v1/lists/:iblockId/elements/:elementId`](/docs/lists/elements/update) | lists.element.update | Update an element |
| DELETE | [`/v1/lists/:iblockId/elements/:elementId`](/docs/lists/elements/delete) | lists.element.delete | Delete an element |
| GET | [`/v1/lists/:iblockId/elements/:elementId/files/:fieldId`](/docs/lists/elements/files) | lists.element.get.file.url | File links from a property |

## Error codes

| HTTP | Code | When |
|------|-----|-------|
| 409 | `LISTS_MODULE_NOT_ENABLED` | The Lists module is not enabled on the portal |
| 400 | `INVALID_IBLOCK_TYPE` | `iblockTypeId` is not one of `lists`, `lists_socnet`, `bitrix_processes` |
| 400 | `MISSING_REQUIRED_FIELDS` | A required `iblockCode`, `sectionCode`, `elementCode`, or `fields` was not provided |
| 400 | `INVALID_PARAMS` | A non-numeric `:sectionId` or `:elementId`, or a `fieldId` with the `PROPERTY_` prefix in the files route |
| 400 | `INVALID_FILTER` | The `filter` parameter is not valid JSON |
| 400 | `INVALID_SORT_FIELD` | The `sort` parameter references an unsupported field or direction |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request. For example, a field is created without `CODE` or updated without `TYPE` |
| 403 | `BITRIX_ACCESS_DENIED` | No permissions for the list, or a list with this `:iblockId` does not exist |
| 404 | `LIST_NOT_FOUND` / `SECTION_NOT_FOUND` / `ELEMENT_NOT_FOUND` / `FIELD_NOT_FOUND` | Object not found |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 403 | `SCOPE_DENIED` | The key lacks the `lists` scope |
| 401 | `TOKEN_MISSING` | `X-Api-Key` was not provided, or the key has no tokens |

The full list of common API errors — [Errors](/docs/errors).

## Limits

| Limit | Value |
|-------|-------|
| List and element pagination | The offset for `GET /v1/lists` and `GET /v1/lists/:iblockId/elements` is set by the `start` parameter or by its alias `offset`. When both are passed, `start` applies. The response is returned in pages. Get the next page by increasing the offset. There is no automatic traversal of all pages |
| Rate limit | Shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Lists](/docs/lists/lists)
- [List fields](/docs/lists/fields)
- [Sections](/docs/lists/sections)
- [Elements](/docs/lists/elements)