Create a section of the universal list lists.section.add

{% note tip "" %}

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

{% endnote %}

Scope: lists

Who can execute the method: a user with "Edit" access permission for the required list

The method lists.section.add creates a list section.

Method Parameters

{% include Note on required parameters %}

#| || Name type | Description || || IBLOCK_TYPE_ID* string | Identifier of the information block type. Possible values:

lists — list information block type
bitrix_processes — processes information block type
lists_socnet — group lists information block type || || IBLOCK_ID* integer | Identifier of the information block.

The identifier can be obtained using the lists.get method || || IBLOCK_CODE* string | Symbolic code of the information block.

The code can be obtained using the lists.get method

{% note info "" %}

At least one of the parameters must be specified: IBLOCK_ID or IBLOCK_CODE

{% endnote %} || || IBLOCK_SECTION_ID integer | Identifier of the parent section.

If the parameter is not provided, the section is created at the root of the list. The default value is 0.

The identifier can be obtained using the lists.section.get method || || SECTION_CODE* string | Symbolic code of the section || || FIELDS* array | Array of fields.

Detailed description || |#

Parameter FIELDS {#parametr-fields}

{% include Note on required parameters %}

#| || Name type | Description || || NAME* string | Name of the section || || EXTERNAL_ID string | External identifier of the section || || XML_ID string | External identifier (XML ID) || || SORT integer | Sorting || || ACTIVE string | Activity status. Possible values:

Y — yes
N — no || || PICTURE array | Deprecated.

Image. An object in the format {fileData: [value1, value2]}, where value1 is the name of the image file with the extension, and value2 is the image in base64 format.

To delete the image, use the object in the format {remove: 'Y'} || || DESCRIPTION string | Deprecated.

Description || || DESCRIPTION_TYPE string | Deprecated.

Description type. Possible values:

text — text
html — HTML

Defaults to text || || DETAIL_PICTURE array | Deprecated.

Detailed image. An object in the format {fileData: [value1, value2]}, where value1 is the name of the image file with the extension, and value2 is the image in base64 format.

To delete the image, use the object in the format {remove: 'Y'} || || SECTION_PROPERTY array | Deprecated.

User properties || |#

Code Examples

{% include Note on examples %}

{% list tabs %}

cURL (Webhook)

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":95,"IBLOCK_SECTION_ID":0,"SECTION_CODE":"marketing_documents","FIELDS":{"NAME":"Marketing Department Documents","EXTERNAL_ID":"ext_marketing_docs_001","XML_ID":"xml_marketing_docs_001","SORT":500,"ACTIVE":"Y"}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/lists.section.add

cURL (OAuth)

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":95,"IBLOCK_SECTION_ID":0,"SECTION_CODE":"marketing_documents","FIELDS":{"NAME":"Marketing Department Documents","EXTERNAL_ID":"ext_marketing_docs_001","XML_ID":"xml_marketing_docs_001","SORT":500,"ACTIVE":"Y"},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/lists.section.add

JS (TS)

// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<number>({
    method: 'lists.section.add',
    params: {
      IBLOCK_TYPE_ID: 'lists',
      IBLOCK_ID: 95,
      IBLOCK_SECTION_ID: 0,
      SECTION_CODE: 'marketing_documents',
      FIELDS: {
        NAME: 'Marketing department documents',
        EXTERNAL_ID: 'ext_marketing_docs_001',
        XML_ID: 'xml_marketing_docs_001',
        SORT: 500,
        ACTIVE: 'Y',
      },
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Created section ID:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

JS (UMD)

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addListsSection() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'lists.section.add',
        params: {
          IBLOCK_TYPE_ID: 'lists',
          IBLOCK_ID: 95,
          IBLOCK_SECTION_ID: 0,
          SECTION_CODE: 'marketing_documents',
          FIELDS: {
            NAME: 'Marketing department documents',
            EXTERNAL_ID: 'ext_marketing_docs_001',
            XML_ID: 'xml_marketing_docs_001',
            SORT: 500,
            ACTIVE: 'Y',
          },
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Created section ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addListsSection)
</script>

PHP

try {
    $response = $b24Service
        ->core
        ->call(
            'lists.section.add',
            [
                'IBLOCK_TYPE_ID' => 'lists',
                'IBLOCK_ID' => 95,
                'IBLOCK_SECTION_ID' => 0,
                'SECTION_CODE' => 'marketing_documents',
                'FIELDS' => [
                    'NAME' => 'Marketing Department Documents',
                    'EXTERNAL_ID' => 'ext_marketing_docs_001',
                    'XML_ID' => 'xml_marketing_docs_001',
                    'SORT' => 500,
                    'ACTIVE' => 'Y',
                ]
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
    processData($result);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding section: ' . $e->getMessage();
}

BX24.js

BX24.callMethod(
    'lists.section.add',
    {
        IBLOCK_TYPE_ID: 'lists', 
        IBLOCK_ID: 95,                              
        IBLOCK_SECTION_ID: 0,
        SECTION_CODE: 'marketing_documents',  

        FIELDS: {
            NAME: 'Marketing Department Documents',                     
            EXTERNAL_ID: 'ext_marketing_docs_001', 
            XML_ID: 'xml_marketing_docs_001',                                         
            SORT: 500,                         
            ACTIVE: 'Y',                                                                        
        }
    },
    function(result) {
        if (result.error()) {
            console.error(result.error());
        } else {
            console.log(result.data());
        }
    }
);

PHP CRest

require_once('crest.php');

$result = CRest::call(
    'lists.section.add',
    [
        'IBLOCK_TYPE_ID' => 'lists',
        'IBLOCK_ID' => 95,
        'IBLOCK_SECTION_ID' => 0,
        'SECTION_CODE' => 'marketing_documents',
        'FIELDS' => [
            'NAME' => 'Marketing Department Documents',
            'EXTERNAL_ID' => 'ext_marketing_docs_001',
            'XML_ID' => 'xml_marketing_docs_001',
            'SORT' => 500,
            'ACTIVE' => 'Y',
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "lists.section.add", b24.Params{
	"IBLOCK_TYPE_ID":    "lists",
	"IBLOCK_ID":         95,
	"IBLOCK_SECTION_ID": 0,
	"SECTION_CODE":      "marketing_documents",
	"FIELDS": b24.Params{
		"NAME":        "Marketing Department Documents",
		"EXTERNAL_ID": "ext_marketing_docs_001",
		"XML_ID":      "xml_marketing_docs_001",
		"SORT":        500,
		"ACTIVE":      "Y",
	},
})
if err != nil {
	return fmt.Errorf("lists.section.add: %w", err)
}

var newID b24.ID
if err := json.Unmarshal(res.Result, &newID); err != nil {
	return fmt.Errorf("parse response: %w", err)
}
fmt.Println("id:", newID)

{% endlist %}

Response Handling

HTTP status: 200

{
    "result": 169,
    "time": {
        "start": 1761554216,
        "finish": 1761554216.280577,
        "duration": 0.2805769443511963,
        "processing": 0,
        "date_start": "2025-10-27T11:36:56+02:00",
        "date_finish": "2025-10-27T11:36:56+02:00",
        "operating_reset_at": 1761554816,
        "operating": 0
    }
}

Returned Data

#| || Name type | Description || || result integer | Identifier of the created section || || time time | Information about the request execution time || |#

Error Handling

HTTP status: 400

{
    "error":"ERROR_REQUIRED_PARAMETERS_MISSING",
    "error_description":"Required parameter is missing"
}

{% include notitle error handling %}

Possible Error Codes

#| || Code | Description | Value || || ERROR_REQUIRED_PARAMETERS_MISSING | Required parameter X is missing | Required parameter is missing || || ERROR_ADD_SECTION | — | Error adding section || || ACCESS_DENIED | Access denied | Insufficient rights to add section || |#

{% include system errors %}

Navigation Menu

Uh oh!

Create a section of the universal list lists.section.add

Method Parameters

Parameter FIELDS {#parametr-fields}

Code Examples

Response Handling

Returned Data

Error Handling

Possible Error Codes

Continue Learning

Uh oh!

FilesExpand file tree

lists-section-add.md

Latest commit

History

lists-section-add.md

File metadata and controls

Create a section of the universal list lists.section.add

Method Parameters

Parameter FIELDS {#parametr-fields}

Code Examples

Response Handling

Returned Data

Error Handling

Possible Error Codes

Continue Learning