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, bitrix_processes, or structure. 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
structure — company structure type (contains the built-in absence calendar infoblock absence)
socnetGroupId number no Workgroup ID from the id field in the List workgroups response. For a workgroup list, pass iblockTypeId: "lists_socnet" and the ID of that group. For a regular list, omit this parameter
messages object no Labels for elements, sections, and their actions in the list interface. Supported fields are listed below. The SECTION_NAME field is ignored
messages.ELEMENTS_NAME string no Plural label for elements, for example Requests
messages.ELEMENT_NAME string no Singular label for an element, for example Request
messages.ELEMENT_ADD string no Label for the action that adds an element
messages.ELEMENT_EDIT string no Label for the action that edits an element
messages.ELEMENT_DELETE string no Label for the action that deletes an element
messages.SECTIONS_NAME string no Plural label for sections, for example Categories
messages.SECTION_ADD string no Label for the action that adds a section
messages.SECTION_EDIT string no Label for the action that edits a section
messages.SECTION_DELETE string no Label for the action that deletes a section
rights object no List access permissions. Each key is a user or department code containing its ID, and each value is a letter code for a permission. Codes and ID sources are described in the RIGHTS parameter in the Bitrix24 reference

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": "Request registry",
      "DESCRIPTION": "Requests 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": "Request registry",
      "DESCRIPTION": "Requests 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: 'Request registry',
      DESCRIPTION: 'Requests 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: 'Request registry',
      DESCRIPTION: 'Requests for processing',
      SORT: 100,
    },
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object List creation result
data.id number Identifier of the created list IBLOCK_ID. Use it to get the list

Response example

HTTP 201 Created:

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, structure
422 BITRIX_ERROR The required fields.NAME field is missing. Bitrix24 returns b24Code: ERROR_REQUIRED_PARAMETERS_MISSING
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