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

Create list

POST /v1/lists

Creates a new list — an infoblock of type lists, lists_socnet, or bitrix_processes. The symbolic code of the new list is passed in the iblockCode field at the top level of the body, outside the fields wrapper, while the list settings go inside fields in Bitrix24 format.

Request fields (body)

Field Type Required Description
iblockCode string yes Symbolic code of the new list. Passed at the top level of the body, outside the fields wrapper
fields object yes List settings in Bitrix24 format. Keys inside are uppercase with underscores
fields.NAME string yes List name
fields.DESCRIPTION string no List description
fields.SORT number no Sort index in the list of lists
fields.BIZPROC string no Enable workflows: Y or N
iblockTypeId string no Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — internal workflows
socnetGroupId number no Workgroup ID. Required when iblockTypeId is lists_socnet, unused for other types
messages object no List interface labels — names for sections and elements
rights object no List access rights by Bitrix24 identifiers

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockCode": "orders_registry",
    "fields": {
      "NAME": "Order registry",
      "DESCRIPTION": "Orders for processing",
      "SORT": 100
    }
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockCode": "orders_registry",
    "fields": {
      "NAME": "Order registry",
      "DESCRIPTION": "Orders for processing",
      "SORT": 100
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockCode: 'orders_registry',
    fields: {
      NAME: 'Order registry',
      DESCRIPTION: 'Orders for processing',
      SORT: 100,
    },
  }),
})

const { data } = await res.json()
console.log('List ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockCode: 'orders_registry',
    fields: {
      NAME: 'Order registry',
      DESCRIPTION: 'Orders for processing',
      SORT: 100,
    },
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data.id number Identifier of the created list IBLOCK_ID

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 133
  }
}

Error response example

400 — a required parameter is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "`iblockCode` is required (the symbolic code of the new list)."
  }
}

Errors

HTTP Code Description
400 MISSING_REQUIRED_FIELDS iblockCode or the fields object is missing
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of lists, lists_socnet, bitrix_processes
409 LISTS_MODULE_NOT_ENABLED The Lists module is not enabled on the Bitrix24 portal
403 WRITE_BLOCKED_READONLY_KEY The key operates in read-only mode
403 SCOPE_DENIED The key lacks the lists scope
401 TOKEN_MISSING The key has no access tokens configured

Full list of common API errors — Errors.

Known specifics

Addressing by code or numeric identifier. The created list is available in subsequent /v1/lists/:iblockId calls both by the numeric id from the response and by the symbolic code from iblockCode.

See also