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
FieldiblockCode Typestring Requiredyes DescriptionSymbolic code of the new list. Passed at the top level of the body, outside the fields wrapper
Fieldfields Typeobject Requiredyes DescriptionList settings in Bitrix24 format. Keys inside are uppercase with underscores
Fieldfields.NAME Typestring Requiredyes DescriptionList name
Fieldfields.DESCRIPTION Typestring Requiredno DescriptionList description
Fieldfields.SORT Typenumber Requiredno DescriptionSort index in the list of lists
Fieldfields.BIZPROC Typestring Requiredno DescriptionEnable workflows: Y or N
FieldiblockTypeId Typestring Requiredno DescriptionInfoblock 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)
FieldsocnetGroupId Typenumber Requiredno DescriptionWorkgroup 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
Fieldmessages Typeobject Requiredno DescriptionLabels for elements, sections, and their actions in the list interface. Supported fields are listed below. The SECTION_NAME field is ignored
Fieldmessages.ELEMENTS_NAME Typestring Requiredno DescriptionPlural label for elements, for example Requests
Fieldmessages.ELEMENT_NAME Typestring Requiredno DescriptionSingular label for an element, for example Request
Fieldmessages.ELEMENT_ADD Typestring Requiredno DescriptionLabel for the action that adds an element
Fieldmessages.ELEMENT_EDIT Typestring Requiredno DescriptionLabel for the action that edits an element
Fieldmessages.ELEMENT_DELETE Typestring Requiredno DescriptionLabel for the action that deletes an element
Fieldmessages.SECTIONS_NAME Typestring Requiredno DescriptionPlural label for sections, for example Categories
Fieldmessages.SECTION_ADD Typestring Requiredno DescriptionLabel for the action that adds a section
Fieldmessages.SECTION_EDIT Typestring Requiredno DescriptionLabel for the action that edits a section
Fieldmessages.SECTION_DELETE Typestring Requiredno DescriptionLabel for the action that deletes a section
Fieldrights Typeobject Requiredno DescriptionList 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionList creation result
Fielddata.id Typenumber DescriptionIdentifier 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
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptioniblockCode or the fields object is missing
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not one of lists, lists_socnet, bitrix_processes, structure
HTTP422 CodeBITRIX_ERROR DescriptionThe required fields.NAME field is missing. Bitrix24 returns b24Code: ERROR_REQUIRED_PARAMETERS_MISSING
HTTP409 CodeLISTS_MODULE_NOT_ENABLED DescriptionThe Lists module is not enabled on the Bitrix24 portal
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key operates in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the lists scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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