Add Block to Page `landing.landing.addblock`

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

Required parameters are marked with *

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

Required parameters are marked with *

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

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

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 -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"

try
        {
        	const response = await $b24.callMethod(
        		'landing.landing.addblock',
        		{
        			lid: 351,
        			fields: {
        				CODE: '02.three_cols_big_1',
        				AFTER_ID: 6428,
        				ACTIVE: 'Y'
        			}
        		}
        	);
        
        	const result = response.getData().result;
        	console.info(result);
        }
        catch (error)
        {
        	console.error(error);
        }

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.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());
                }
            }
        );

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>';
        }

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'`

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."
        }

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

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

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not allowed to be called using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The methods must be called using the HTTPS protocol
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block, to remove it you need to contact Bitrix24 technical support
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is available only on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user whose access token or webhook was used to call the method lacks permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the account administrator has allowed access to this application only for specific users
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the option "Temporary closure of the public part of the site". Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

List of Methods for Working with Blocks

Copy Block to Page

Add Block to Page landing.landing.addblock

Method ParametersMethod Parameters

Parameter fieldsParameter fields

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

Result Object whenResult Object when RETURN_CONTENT = 'Y'

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning