Add Block to Page landing.landing.addblock

{% 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: landing

Who can execute the method: user with "edit" access permission for the site

The method landing.landing.addblock adds a new block to the page and returns the identifier of the created block.

If the page is already published, the new block will be visible to visitors after the "Publish Changes" command in the interface or after calling the method landing.landing.publication.

Method Parameters

{% include Note on required parameters %}

#| || Name type | Description || || scope string | Internal scope of landings. It is not related to the REST scope landing in the method name.

For pages of types PAGE, STORE, and SMN, this parameter does not need to be passed. For pages in the scopes GROUP, KNOWLEDGE, and MAINPAGE, pass the same value for scope. The rules for selecting the value are described in the article Working with Site Types and Scopes || || lid* integer | Page identifier.

The page identifier can be obtained using the method landing.landing.getList, as well as from the results of the methods landing.landing.add, landing.landing.addByTemplate, and landing.landing.copy || || fields* object | Set of parameters for the new block (detailed description) || || preventHistory boolean | If true, the method does not add the action to the page change history. Default is false || |#

Parameter fields {#fields}

{% include Note on required parameters %}

#| || Name type | Description || || CODE* string | Symbolic code of the block from the repository.

The code can be obtained using the method landing.block.getrepository: for fields.CODE, take the key of the element from result.items, for example 02.three_cols_big_1 or repo_385.

For a block registered by the application through landing.repo.register, use a value in the form of repo_<ID>.

The availability of the code depends on the type of page and the top-level parameter scope, if it is passed. If you obtain the code via landing.block.getrepository, use the same scope as in landing.landing.addblock.

If the parameter is not passed or passed as an empty string, the method will return an error || || AFTER_ID integer | Identifier of the block after which the new block should be inserted.

The block identifier can be obtained using the method landing.block.getList.

If you pass the identifier of an existing block on the page, the new block will be added immediately after it. If the parameter is not passed, the new block will be added to the beginning of the page.

If AFTER_ID is passed but there is no block with that identifier on the page, there will be no separate error. In this case, the new block will also be added to the beginning of the page || || ACTIVE string | Flag indicating the activity of the new block. Possible values:

Y — block is active N — block is inactive

Default is Y || || CONTENT string | HTML content of the block. Allows replacing the standard content of the block with your own HTML code. The block code must still be available in the repository for the current type of page and scope. Before saving, the value is cleaned and validated || || RETURN_CONTENT string | If Y is passed, after adding the block, the method will return not only its identifier but also the block data (detailed description). For any other value, the method will return only the block identifier || |#

Code Examples

{% include Note on examples %}

{% list tabs %}

cURL (Webhook)

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "lid": 351,
    "fields": {
      "CODE": "02.three_cols_big_1",
      "AFTER_ID": 6428,
      "ACTIVE": "Y"
    }
  }' \
  "https://**put.your-domain-here**/rest/**user_id**/**webhook_code**/landing.landing.addblock.json"

cURL (OAuth)

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "lid": 351,
    "fields": {
      "CODE": "02.three_cols_big_1",
      "AFTER_ID": 6428,
      "ACTIVE": "Y"
    },
    "auth": "**put_access_token_here**"
  }' \
  "https://**put.your-domain-here**/rest/landing.landing.addblock.json"

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: 'landing.landing.addblock',
    params: {
      lid: 351,
      fields: {
        CODE: '02.three_cols_big_1',
        AFTER_ID: 6428,
        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('New block 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 addBlock() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'landing.landing.addblock',
        params: {
          lid: 351,
          fields: {
            CODE: '02.three_cols_big_1',
            AFTER_ID: 6428,
            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('New block ID:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

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

Python

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.landing.landing.addblock(
        lid=351,
        fields={
            "CODE": "02.three_cols_big_1",
            "AFTER_ID": 6428,
            "ACTIVE": "Y",
        },
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Bitrix API error",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Bitrix SDK error: {error.message}")
except Exception as error:
    print(f"Unexpected error: {error}")

PHP

try {
    $response = $b24Service
        ->core
        ->call(
            'landing.landing.addblock',
            [
                'lid' => 351,
                'fields' => [
                    'CODE' => '02.three_cols_big_1',
                    'AFTER_ID' => 6428,
                    'ACTIVE' => 'Y',
                ],
            ]
        );

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

    echo 'Success: ' . var_export($result, true);
} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error adding block: ' . $e->getMessage();
}

BX24.js

BX24.callMethod(
    'landing.landing.addblock',
    {
        lid: 351,
        fields: {
            CODE: '02.three_cols_big_1',
            AFTER_ID: 6428,
            ACTIVE: 'Y'
        }
    },
    function(result)
    {
        if (result.error())
        {
            console.error(result.error());
        }
        else
        {
            console.info(result.data());
        }
    }
);

PHP CRest

require_once('crest.php');

$result = CRest::call(
    'landing.landing.addblock',
    [
        'lid' => 351,
        'fields' => [
            'CODE' => '02.three_cols_big_1',
            'AFTER_ID' => 6428,
            'ACTIVE' => 'Y',
        ],
    ]
);

if (isset($result['error']))
{
    echo 'Error: ' . $result['error_description'];
}
else
{
    echo '<pre>';
    print_r($result['result']);
    echo '</pre>';
}

// client and ctx are already created — see the Go SDK section
res, err := client.Core().Call(ctx, "landing.landing.addblock", b24.Params{
	"lid": 351,
	"fields": b24.Params{
		"CODE":     "02.three_cols_big_1",
		"AFTER_ID": 6428,
		"ACTIVE":   "Y",
	},
})
if err != nil {
	return fmt.Errorf("landing.landing.addblock: %w", err)
}

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

{% endlist %}

Response Handling

HTTP status: 200

{
    "result": 28597,
    "time": {
        "start": 1773923439,
        "finish": 1773923439.57418,
        "duration": 0.5741798877716064,
        "processing": 0,
        "date_start": "2026-03-19T15:30:39+02:00",
        "date_finish": "2026-03-19T15:30:39+02:00",
        "operating_reset_at": 1773924039,
        "operating": 0.10522103309631348
    }
}

Returned Data

#| || Name type | Description || || result integer | object | Identifier of the created block. If fields.RETURN_CONTENT = 'Y' is passed, the method will return the block object (detailed description) || || time time | Information about the execution time of the request || |#

Result Object when `RETURN_CONTENT = 'Y'` {#result-content}

#| || Name type | Description || || id integer | Identifier of the created block || || sections string | Codes of the block sections from the manifest, concatenated into a single string with commas || || active boolean | Indicator of the block's activity || || access string | Access level to the block || || anchor string | Local anchor of the block. By default, the new block receives an anchor in the form b<ID>, for example b28597 || || php boolean | Indicator that there is PHP code in the block's content || || designed boolean | Indicator of a designed block || || repoId integer | Identifier of the REST block from the repository or null if the block is not linked to a REST repository || || content string | Prepared HTML code of the block || || content_ext string | Additional HTML code of connected extensions || || css array | List of CSS resources for the block || || js array | List of JS resources for the block. For standard blocks from the repository, this field may contain connections. For REST blocks of the form repo_<ID> when RETURN_CONTENT = 'Y', this field returns an empty array || || assetStrings array | Initialization strings for resources that need to be added to the page || || lang array | object | Language messages of connected extensions. If messages exist, the field returns as an object in key-value form. If there are no additional messages, it may return an empty array || || manifest object | Manifest of the block. The format is described in the section Block Manifest || || dynamicParams array | Parameters of the dynamic block || || requiredUserAction array | The field contains the same data as manifest.requiredUserAction. It is returned only when the user must perform an additional action on the client side after adding the block. The specific data in the field depends on the block's manifest || |#

Error Handling

HTTP status: 400

{
    "error": "BLOCK_CANT_BE_ADDED",
    "error_description": "Cannot add block because it is not intended for this type of page."
}

{% include notitle error handling %}

Possible Error Codes

#| || Code | Description || || MISSING_PARAMS | Required top-level parameter lid or fields is missing || || LANDING_NOT_EXIST | Page with identifier lid not found || || ACCESS_DENIED | User does not have permission to call the method or does not have permission to edit the page || || BLOCK_CANT_BE_ADDED | Code from fields.CODE is not available in the repository, this block cannot be added to the current type of page, or the passed scope has restricted the set of available blocks. The same error is returned if fields.CODE is not passed or passed as an empty string || || BLOCK_WRONG_VERSION | The version of the block from the repository is higher than the version of the installed landing module || || BLOCK_NOT_FOUND | Content for the block not found, including if an empty fields.CONTENT is passed || |#

{% include system errors %}

Navigation Menu

Uh oh!

Add Block to Page landing.landing.addblock

Method Parameters

Parameter fields {#fields}

Code Examples

Response Handling

Returned Data

Result Object when `RETURN_CONTENT = 'Y'` {#result-content}

Error Handling

Possible Error Codes

Continue Learning

Uh oh!

FilesExpand file tree

landing-landing-add-block.md

Latest commit

History

landing-landing-add-block.md

File metadata and controls

Add Block to Page landing.landing.addblock

Method Parameters

Parameter fields {#fields}

Code Examples

Response Handling

Returned Data

Result Object when RETURN_CONTENT = 'Y' {#result-content}

Error Handling

Possible Error Codes

Continue Learning

Result Object when `RETURN_CONTENT = 'Y'` {#result-content}