Get CRM Form Placement Options crm.form.embedding.get

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: crm

Who can execute the method: a user with permission to view CRM forms

The method belongs to REST 3.0. The call specifics and response format of the new API version are described in the REST 3.0 overview.

The method crm.form.embedding.get returns the code for placing a CRM form on a website and the public link to the form.

Method Parameters

Required parameters are marked with *

Name
type

Description

id*
integer

CRM form identifier.

The identifier can be obtained using the crm.form.list method

variant
string

The placement option to return. If the parameter is not passed, the method returns all options.

Possible values:

  • inline — the form is embedded in a website page
  • click — the form opens when a button or link is clicked
  • auto — the form opens automatically after a set delay
  • link — a public link to the form

buttonText
string

Text of the button or link that opens the form. The value is inserted only into the returned code and is not saved in the form.

Use it if variant is click. If only buttonType is passed, the method takes the button text from the form settings, and if there is none, uses the default text

buttonType
string

Type of the element that opens the form. The value is inserted only into the returned code and is not saved in the form.

Possible values:

  • button — a button
  • link — a link

Default: button

Use it if variant is click

delay
integer

Auto-display delay of the form in seconds. The value is inserted only into the returned code and is not saved in the form.

Allowed values are listed in auto.options.delay of the method response without the variant parameter, for example 3, 5, 7, 10, 15, 20, 25, 30, 40, 60, 120.

Use it if variant is auto

Code Examples

How to Use Examples in Documentation

The new API call differs by adding the /api/ segment to the request URL:

https://{installation_address}/rest/api/{user_id}/{webhook_token}/crm.form.embedding.get

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"id":45}' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.form.embedding.get
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"id":45,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/api/crm.form.embedding.get
        
import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        type EmbeddingVariant = {
          code: string | null
          previewUrl: string
          settings: Record<string, unknown> | null
          options: Record<string, unknown> | null
        }
        
        type FormEmbeddingGetResult = {
          item: {
            formActive: boolean
            resourcesReady: boolean
            publicUrl: string
            inline: EmbeddingVariant
            click: EmbeddingVariant
            auto: EmbeddingVariant
          }
        }
        
        try {
          const response = await $b24.actions.v3.call.make<FormEmbeddingGetResult>({
            method: 'crm.form.embedding.get',
            params: {
              id: 45,
            },
            requestId: Text.getUuidRfc4122()
          })
        
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info(result.item.publicUrl, result.item.inline.code)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function getFormEmbedding() {
            try {
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v3.call.make({
                method: 'crm.form.embedding.get',
                params: {
                  id: 45,
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info(result.item.publicUrl, result.item.inline.code)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', getFormEmbedding)
        </script>
        
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.crm.form.embedding.get(
                id=45,
            ).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}")

SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via curl or fetch.

try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.form.embedding.get',
                    [
                        'id' => 45,
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            if ($result->error()) {
                error_log($result->error());
            } else {
                echo 'Success: ' . print_r($result->data(), true);
            }
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error: ' . $e->getMessage();
        }

SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via curl or fetch.

BX24.callMethod(
            'crm.form.embedding.get',
            {
                id: 45,
            },
            result => {
                if (result.error())
                    console.error(result.error());
                else
                    console.dir(result.data());
            }
        );

SDKs do not yet support the /rest/api/ address in calls. Use direct HTTP requests, for example, via curl or fetch.

require_once('crest.php');
        
        $result = CRest::call(
            'crm.form.embedding.get',
            [
                'id' => 45,
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        
res, err := client.Core().Call(ctx, "crm.form.embedding.get", b24.Params{
        	"id": 45,
        }, b24.WithIdempotent())
        if err != nil {
        	return fmt.Errorf("crm.form.embedding.get: %w", err)
        }
        
        raw, ok := b24.Unwrap(res.Result, "item")
        if !ok {
        	return fmt.Errorf("no item key in the response")
        }
        
        var item struct {
        	FormActive     bool   `json:"formActive"`
        	ResourcesReady bool   `json:"resourcesReady"`
        	PublicURL      string `json:"publicUrl"`
        	Inline         struct {
        		Code       *string `json:"code"`
        		PreviewURL string  `json:"previewUrl"`
        	} `json:"inline"`
        }
        if err := json.Unmarshal(raw, &item); err != nil {
        	return fmt.Errorf("parsing the response: %w", err)
        }
        fmt.Println(item.PublicURL)

Response Handling

HTTP status: 200

Response without the variant parameter:

{
            "result": {
                "item": {
                    "formActive": true,
                    "resourcesReady": true,
                    "publicUrl": "https://example.bitrix24site.com/crm_form_nscnl/?telemetry_sign=v1%3A45%3Adirect_link.0960d174ab4aa87739668fbe63deae0a790b4f7254670a3b36d646588fa04242",
                    "inline": {
                        "code": "<script data-b24-form=\"inline/45/6el0zj\" data-b24-form-telemetry-sign=\"v1:45:site.d77c41d60d0649b2310bbe359cfd319772d16a2387b2e14f10c9e830ae76eb39\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn-com.bitrix24.com/b1234567/crm/form/loader_45.js');\n</script>",
                        "previewUrl": "https://test.bitrix24.com/pub/form/45/6el0zj/?view=preview&preview=inline",
                        "settings": null,
                        "options": null
                    },
                    "click": {
                        "code": "<script data-b24-form=\"click/45/6el0zj\" data-b24-form-telemetry-sign=\"v1:45:site.d77c41d60d0649b2310bbe359cfd319772d16a2387b2e14f10c9e830ae76eb39\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn-com.bitrix24.com/b1234567/crm/form/loader_45.js');\n</script>",
                        "previewUrl": "https://test.bitrix24.com/pub/form/45/6el0zj/?view=preview&preview=click",
                        "settings": {
                            "type": "panel",
                            "position": "right",
                            "vertical": "bottom",
                            "button": {
                                "use": false,
                                "text": null,
                                "font": null,
                                "align": null,
                                "plain": false,
                                "rounded": false,
                                "outlined": false,
                                "decoration": null,
                                "color": {
                                    "text": null,
                                    "textHover": null,
                                    "background": null,
                                    "backgroundHover": null
                                }
                            }
                        },
                        "options": {
                            "type": ["popup", "panel"],
                            "position": ["left", "center", "right"],
                            "vertical": ["bottom", "top"],
                            "button": {
                                "font": ["modern", "classic", "elegant"],
                                "align": ["inline", "left", "center", "right"]
                            }
                        }
                    },
                    "auto": {
                        "code": "<script data-b24-form=\"auto/45/6el0zj\" data-b24-form-telemetry-sign=\"v1:45:site.d77c41d60d0649b2310bbe359cfd319772d16a2387b2e14f10c9e830ae76eb39\" data-skip-moving=\"true\">\n\t(function(w,d,u){\n\t\tvar s=d.createElement('script');s.async=true;s.src=u+'?'+(Date.now()/180000|0);\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://cdn-com.bitrix24.com/b1234567/crm/form/loader_45.js');\n</script>",
                        "previewUrl": "https://test.bitrix24.com/pub/form/45/6el0zj/?view=preview&preview=auto",
                        "settings": {
                            "type": "popup",
                            "position": "center",
                            "vertical": "bottom",
                            "delay": 5
                        },
                        "options": {
                            "type": ["popup", "panel"],
                            "position": ["left", "center", "right"],
                            "vertical": ["bottom", "top"],
                            "delay": [3, 5, 7, 10, 15, 20, 25, 30, 40, 60, 120]
                        }
                    }
                }
            },
            "time": {
                "start": 1792593809,
                "finish": 1792593809.843669,
                "duration": 0.8436689376831055,
                "processing": 0,
                "date_start": "2026-10-21T17:43:29+02:00",
                "date_finish": "2026-10-21T17:43:29+02:00",
                "operating_reset_at": 1792594380,
                "operating": 0
            }
        }

Response with the "variant":"auto" and "delay":10 parameters:

{
            "result": {
                "item": {
                    "variant": "auto",
                    "code": "<script id=\"bx24_form_delay\" data-skip-moving=\"true\">\n\t(function(w,d,u,b){w['Bitrix24FormObject']=b;w[b] = w[b] || function(){arguments[0].ref=u;\n\t\t(w[b].forms=w[b].forms||[]).push(arguments[0])};\n\t\tif(w[b]['forms']) return;\n\t\tvar s=d.createElement('script');s.async=1;s.src=u+'?'+(1*new Date());\n\t\tvar h=d.getElementsByTagName('script')[0];h.parentNode.insertBefore(s,h);\n\t})(window,document,'https://test.bitrix24.com/bitrix/js/crm/form_loader.js','b24form');\n\n\tb24form({\"id\":45,\"lang\":\"en\",\"sec\":\"6el0zj\",\"type\":\"delay\",\"delay\":10});\n</script>"
                }
            },
            "time": {
                "start": 1792594117,
                "finish": 1792594117.571196,
                "duration": 0.5711960792541504,
                "processing": 0,
                "date_start": "2026-10-21T17:48:37+02:00",
                "date_finish": "2026-10-21T17:48:37+02:00",
                "operating_reset_at": 1792594680,
                "operating": 0.4092140197753906
            }
        }

Response with the "variant":"link" parameter:

{
            "result": {
                "item": {
                    "variant": "link",
                    "url": "https://example.bitrix24site.com/crm_form_nscnl/?telemetry_sign=v1%3A45%3Adirect_link.0960d174ab4aa87739668fbe63deae0a790b4f7254670a3b36d646588fa04242"
                }
            },
            "time": {
                "start": 1792594113,
                "finish": 1792594113.75192,
                "duration": 0.7519199848175049,
                "processing": 0,
                "date_start": "2026-10-21T17:48:33+02:00",
                "date_finish": "2026-10-21T17:48:33+02:00",
                "operating_reset_at": 1792594680,
                "operating": 0
            }
        }

Returned Data

Name
type

Description

result
object

Object with the response data

item
object

Form placement options. The content depends on the variant parameter:

time
time

Information about the request execution time

Item Object Without the variant Parameter

Name
type

Description

formActive
boolean

Whether the form is active.

Possible values:

  • true — the form is active and accepts submissions
  • false — the form is deactivated. You can activate it with the crm.form.activate method

resourcesReady
boolean

Whether the form files are built for publication.

Possible values:

  • true — the files are built, the embed codes are ready
  • false — the files are not built yet, code is null for all options

publicUrl
string

Public link to the form

inline
object

Option for embedding the form in a website page. This option has no settings, so settings and options are null, detailed description

click
object

Option for showing the form when a button or link is clicked, detailed description

auto
object

Option for showing the form automatically after a set delay, detailed description

Inline, Click, Auto Objects

Name
type

Description

code
string

HTML code to insert on a website. It is null until the form files are built

previewUrl
string

Link to the form preview in this placement option

settings
object

Current display settings. Present only for the click and auto options, detailed description

options
object

Allowed values of the display settings. Present only for the click and auto options, detailed description

Settings Object

If a setting value is not saved in the form, null is returned. In this case, the default value is applied on the website.

Name
type

Description

type
string

Form window type.

Possible values:

  • popup — a pop-up window
  • panel — a side panel

position
string

Horizontal position of the window.

Possible values:

  • left — on the left
  • center — in the center
  • right — on the right

vertical
string

Vertical position of the window.

Possible values:

  • bottom — at the bottom
  • top — at the top

delay
integer

Auto-display delay in seconds. Present only for the auto option

button
object

Settings of the button that opens the form. Present only for the click option, detailed description

Button Object

Name
type

Description

use
boolean

Whether to show the Bitrix24 button on the website.

Possible values:

  • true — show the button with the settings from this object
  • false — do not show the button

text
string

Button text

font
string

Button font. Allowed values are listed in click.options.button.font, for example modern, classic, elegant

align
string

Button alignment. Allowed values are listed in click.options.button.align, for example inline, left, center, right

plain
boolean

Indicates a button without a background.

Possible values:

  • true — the button has no background
  • false — the button has a background

rounded
boolean

Indicates rounded corners.

Possible values:

  • true — the corners are rounded
  • false — the corners are square

outlined
boolean

Indicates a button outline.

Possible values:

  • true — the button has an outline
  • false — the button has no outline

decoration
string

Button text underline. The interface offers the values dotted, solid, or an empty value

color
object

Button colors in HEX format, for example #3bc8f5 or #3eddffa6 with transparency:

  • text — text color
  • textHover — text color on hover
  • background — background color
  • backgroundHover — background color on hover

Options Object

Name
type

Description

type
string[]

Allowed values of settings.type

position
string[]

Allowed values of settings.position

vertical
string[]

Allowed values of settings.vertical

delay
integer[]

Allowed values of settings.delay. Present only for the auto option

button
object

Allowed values of the button settings: font and align. Present only for the click option

Item Object with the variant Parameter

Name
type

Description

variant
string

Selected placement option: inline, click, auto, or link

code
string

HTML code to insert on a website. Returned for the inline, click, and auto options

url
string

Public link to the form. Returned for the link option

Error Handling

HTTP status: 400

{
            "error": {
                "code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION",
                "message": "Error validating request object.",
                "validation": [
                    {
                        "message": "delay is available only for the auto embedding variant.",
                        "field": "delay"
                    }
                ]
            }
        }

Name
type

Description

error.code
string

String error code. Use it to identify the type of exception

error.message
string

Text description of the error

error.validation
array

Array with error details. Present only in data validation errors BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

error.validation[].field
string

Name of the field where the validation error occurred

error.validation[].message
string

Description of the error related to the specified field

Possible Error Codes

Request Validation Errors

HTTP status: 400

Error Code: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

Field

Error description

How to Fix

id

Required field id is missing

Pass the form id

variant

Field value is not one of the possible values: inline, click, auto, link

Pass one of the values inline, click, auto, link

buttonType

Field value is not one of the possible values: button, link

Pass button or link

buttonText

buttonText is available only for the click embedding variant.

Pass buttonText only together with "variant":"click"

buttonType

buttonType is available only for the click embedding variant.

Pass buttonType only together with "variant":"click"

delay

delay is available only for the auto embedding variant.

Pass delay only together with "variant":"auto"

delay

Embedding delay 11 is not supported

Pass a value from auto.options.delay

Form Not Found Error

HTTP status: 404

Error Code: BITRIX_REST_V3_EXCEPTION_ENTITYNOTFOUNDEXCEPTION

Field

Error description

How to Fix

id

Entity with ID 999999 was not found

Check the form identifier with the crm.form.list method

Access Errors

HTTP status: 403

Error Code: BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION

Field

Error description

How to Fix

-

Access denied

Check that the user has permission to view CRM forms

Error Code: BITRIX_CRM_V2_INFRASTRUCTURE_REST_EXCEPTION_FORM_PHONEVERIFICATIONREQUIREDEXCEPTION

Field

Error description

How to Fix

-

Confirm your phone number to add CRM forms

Verify the phone number in Bitrix24 and repeat the request

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status

Code
Error Message

Description

500

INTERNAL_SERVER_ERROR
Internal server error

An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

503

QUERY_LIMIT_EXCEEDED
Too many requests

The request intensity limit has been exceeded

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit

401

NO_AUTH_FOUND
Wrong authorization data

The request contains no authorization data: neither an access token nor a webhook code was passed

401

INVALID_REQUEST
Https required

Methods are called over the HTTPS protocol only

401

OVERLOAD_LIMIT
REST API is blocked due to overload

The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support

401

ACCESS_DENIED
REST is available only on commercial plans

REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

No active webhook with the specified user identifier and secret code was found

404

ERROR_METHOD_NOT_FOUND
Method not found!

No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with provided by the access token

401

expired_token
The access token provided has expired

The access token has expired

401

user_access_error
The user does not have access to the application

The application is installed, but the Bitrix24 administrator has granted access to it only to specific users

403

PORTAL_DELETED
Portal was deleted

The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Previous
Overview of Methods
Next
Update CRM Form Placement Settings