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

Get a list

GET /v1/lists/:iblockId

Returns the metadata of a single list — name, symbolic code, infoblock type, and settings. The list is addressed by a numeric identifier or a symbolic code.

Parameters

Parameter Type Required Description
iblockId (path) string yes The numeric IBLOCK_ID or symbolic code of the list. Identifiers are available via GET /v1/lists
iblockTypeId (query) string no Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows
structure — company-structure type (stock absence-calendar iblock absence)
socnetGroupId (query) number no Workgroup identifier for the lists_socnet type

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — OAuth application

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

Response fields

Response fields are in Bitrix24 form: keys are uppercase with underscores, numeric values and flags (Y/N) come as strings, unset fields are null.

Field Type Description
success boolean Always true on success
data.ID string The list identifier IBLOCK_ID
data.NAME string List name
data.IBLOCK_TYPE_ID string Infoblock type
data.CODE string Symbolic code. Comes as null if the code is not set
data.DESCRIPTION string List description
data.ACTIVE string Active state: Y or N
data.SORT string Sort index
data.TIMESTAMP_X string Date of last modification
data.BIZPROC string Whether workflows are available: Y or N
data.ELEMENTS_NAME string Plural name for the list's elements
data.SECTIONS_NAME string Plural name for sections

The main fields are shown. The list object also contains other Bitrix24 infoblock metadata fields.

Response example

JSON 
{
  "success": true,
  "data": {
    "ID": "121",
    "NAME": "Task list",
    "IBLOCK_TYPE_ID": "lists",
    "CODE": "my_list",
    "DESCRIPTION": "A list for managing daily tasks",
    "ACTIVE": "Y",
    "SORT": "600",
    "TIMESTAMP_X": "12/11/2025 11:40:53 am",
    "BIZPROC": "N",
    "ELEMENTS_NAME": "Items",
    "SECTIONS_NAME": "Categories"
  }
}

Error response example

403 — no permissions for the list, or a list with this identifier does not exist:

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 allowed set
403 BITRIX_ACCESS_DENIED No permissions for the list. An absent list lands here too when its id is NUMERIC: Bitrix24 answers such an id with a permission refusal rather than an empty result
404 LIST_NOT_FOUND Bitrix24 returned an empty result. That is how a SYMBOLIC id of an absent list answers, and also an accessible list with no data
409 LISTS_MODULE_NOT_ENABLED The Lists module is not enabled on the portal
403 SCOPE_DENIED The API key lacks the lists scope
401 TOKEN_MISSING The API key has no configured tokens

The full list of common API errors — Errors.

Known specifics

A list is addressed by identifier or code. An :iblockId segment of digits only is treated as the numeric IBLOCK_ID, any other value as the symbolic code. Some lists have CODE equal to null — such a list is available only by the numeric identifier.

See also