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
iblockId (path) string yes Numeric IBLOCK_ID or the list's symbolic code

Request body fields

Field Type Required Description
sectionCode string yes Symbolic code of the new section. Passed at the top level of the body, outside the fields wrapper
fields object yes Section fields in the Bitrix24 form. Keys inside are uppercase with underscores
fields.NAME string yes Section name
fields.SORT number no Sort index in the list of sections
fields.DESCRIPTION string no Section description
iblockSectionId number no ID 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
iblockTypeId string no Infoblock type. Values:
lists — regular lists, default
lists_socnet — workgroup lists
bitrix_processes — service workflows

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
success boolean Always true on success
data.id number ID 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
400 MISSING_REQUIRED_FIELDS sectionCode or the fields object is missing
400 INVALID_IBLOCK_TYPE iblockTypeId is not one of lists, lists_socnet, bitrix_processes
403 BITRIX_ACCESS_DENIED The list does not exist or the key has no access to it
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 is missing the lists scope
401 TOKEN_MISSING The 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