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

Create a section

POST /v1/lists/:iblockId/sections

Creates a new section in a list. The section's symbolic code is passed in the sectionCode field at the top level of the body, outside the fields wrapper, while the section fields go inside fields in the Bitrix24 form.

Parameters

Parameter Type Required Description
ParameteriblockId (path) Typestring Requiredyes DescriptionNumeric IBLOCK_ID or the list's symbolic code

Request body fields

Field Type Required Description
FieldsectionCode Typestring Requiredyes DescriptionSymbolic code of the new section. Passed at the top level of the body, outside the fields wrapper
Fieldfields Typeobject Requiredyes DescriptionSection fields in the Bitrix24 form. Keys inside are uppercase with underscores
Fieldfields.NAME Typestring Requiredyes DescriptionSection name
Fieldfields.SORT Typenumber Requiredno DescriptionSort index in the list of sections
Fieldfields.DESCRIPTION Typestring Requiredno DescriptionSection description
FieldiblockSectionId Typenumber Requiredno DescriptionID of the parent section for nesting. A value of 0 or an absent field creates the section at the root of the list. List of sections: GET /v1/lists/:iblockId/sections
FieldiblockTypeId Typestring Requiredno DescriptionInfoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows
structure — company-structure type (absence-calendar iblock absence)

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists/23/sections \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sectionCode": "region_north",
    "fields": {
      "NAME": "Northern region",
      "SORT": 100,
      "DESCRIPTION": "Requests for the northern region"
    }
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/lists/23/sections \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sectionCode": "region_north",
    "fields": {
      "NAME": "Northern region",
      "SORT": 100,
      "DESCRIPTION": "Requests for the northern region"
    }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sectionCode: 'region_north',
    fields: {
      NAME: 'Northern region',
      SORT: 100,
      DESCRIPTION: 'Requests for the northern region',
    },
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/lists/23/sections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sectionCode: 'region_north',
    fields: {
      NAME: 'Northern region',
      SORT: 100,
      DESCRIPTION: 'Requests for the northern region',
    },
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID of the created section

Response example

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

Error response example

400 — a required parameter is missing:

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

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionsectionCode or the fields object is missing
HTTP400 CodeINVALID_IBLOCK_TYPE DescriptioniblockTypeId is not one of lists, lists_socnet, bitrix_processes, structure
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe list does not exist or the key has no access to it
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 is missing the lists scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no access tokens configured

Full list of common API errors — Errors.

Known specifics

Nesting via iblockSectionId. A section is placed inside another section when the parent ID is passed in iblockSectionId. Without this field or with a value of 0, the section is created at the top level of the list.

See also