Data Types and Object Structure in the CRM Forms REST API

Object

When to Use

Methods

crm_form

To read, create, and update a CRM form: fields, CRM scheme, appearance, consents, post-submission actions, integrations

crm.form.*

crm_form_configuration

To retrieve the values required to create a form: CRM schemes, pipelines, field types, languages, payment systems, permissions, and the active forms limit

crm.form.configuration.get

crm_form_scenario

To choose a ready-made form scenario

crm.form.scenario.list

crm_form_scenario_category

To group scenarios by category

crm.form.scenariocategory.list

crm_form_entity_field

To choose the CRM object fields the form is built from

crm.form.entityfield.list

crm_form_embedding

To retrieve the embed code, the public link, and the button and auto-display settings

crm.form.embedding.*

crm_form_embedding_selection

To retrieve the code of a single placement option

crm.form.embedding.get

crm_form_site_button

To check which website widgets the form is connected to

crm.form.sitebutton.list

crm_form_open_line

To check in which Open Channels the form is the welcome form

crm.form.openline.list

Type

Descriptions and Values

crm_form.id

Integer identifier of a CRM form, for example 45. Form identifiers can be retrieved with crm.form.list

crm_form.updatedTime

Form version — the date and time of the last change in ISO 8601 format, for example 2026-10-21T17:44:00+02:00. Can be retrieved with crm.form.get. Required in crm.form.update and crm.form.embedding.update

crm_form_configuration.entitySchemes.id

Integer identifier of a CRM scheme, for example 1 — lead. Passed in crm.entityScheme. Can be retrieved with crm.form.configuration.get

crm_form_configuration.dealCategories.id

Integer identifier of a deal pipeline, 0 — the general pipeline. Passed in crm.dealCategoryId

crm_form_configuration.smartProcesses.categories.id

Integer identifier of an SPA pipeline. Passed in crm.smartProcessCategoryId

crm_form_configuration.fieldTypes.id

String code of a form field type, for example string or phone. Passed in fields[].type

crm_form_configuration.languages.id

String code of the form language, for example en. Passed in languageId

crm_form_configuration.paySystems.id

Integer identifier of a payment system. Passed in payment.disabledPaySystemsId

crm_form_scenario.id

String code of a scenario, for example contacts or callback. Passed in templateId. Can be retrieved with crm.form.scenario.list

crm_form_scenario_category.id

String code of a scenario category, for example crm. Can be retrieved with crm.form.scenariocategory.list

crm_form_entity_field.name

String code of a CRM object field, for example LEAD_NAME. Passed in fields[].name. Can be retrieved with crm.form.entityfield.list

crm_form_site_button.id

Integer identifier of a website widget. Can be retrieved with crm.form.sitebutton.list

crm_form_open_line.id

Integer identifier of an Open Channel. Can be retrieved with crm.form.openline.list

Name
type

Description

Write

id
integer

Form identifier

Read-only

code
string

Form symbolic code

Read-only

name
string

Form name, up to 50 characters

Required on creation

active
boolean

Form activity.

Possible values:

• true — the form is active and accepts submissions
• false — the form is deactivated

Passed only in crm.form.add, true by default. For an existing form, the activity is changed by crm.form.activate and crm.form.deactivate

On creation only

system
boolean

System form flag. A system form cannot be updated or deleted

Possible values:

• true — the form is a system form
• false — the form was created by a user

Read-only

languageId
string

Form language. crm.form.configuration.get returns the list of languages in the languages key

Yes

templateId
string

Scenario the form was created from, for example contacts or callback. crm.form.scenario.list returns the list of scenarios

Yes

createdTime
datetime

Form creation date and time

Read-only

updatedTime
datetime

Form version — the date and time of the last change. Passed in updatedTime of the update methods so as not to overwrite someone else's changes

Read-only

activeChangedById
integer

Identifier of the user who last activated or deactivated the form

Read-only

activeChangedTime
datetime

Date and time the form was last activated or deactivated

Read-only

appearance
object

Form title, description, and button. Section structure

Yes

crm
object

CRM objects the form creates. Section structure

Yes

fields
array

Form fields. The element structure is described below

Yes

dependencies
array

Dependent field rules. Element structure

Yes

presetFields
array

CRM field values the form fills in automatically. Element structure

Yes

responsible
object

Responsible persons queue. Section structure

Yes

agreements
object

Consents the customer accepts. Section structure

Yes

submission
object

What the customer sees after submitting the form. Section structure

Yes

payment
object

Payment after the form is submitted. Section structure

Yes

callback
object

Callback after the form is submitted. Section structure

Yes

booking
object

Online booking. Contains the enabled field of the boolean type: true if the form has a booking field

Read-only

analytics
object

Web analytics counters. Section structure

Yes

spamProtection
object

Spam protection. Contains the enabled field of the boolean type: true — protection is enabled, false — disabled

Yes

integrations
object

Integrations with messengers and advertising services. Section structure

Yes

Name
type

Description

Write

title
string

Form title

Yes

description
string

Description below the title

Yes

buttonCaption
string

Submit button text

Yes

buttonTextColor
string

Button text color

Yes

buttonBackgroundColor
string

Button background color

Yes

backgroundImageId
integer

Background image identifier

Read-only

copyrightRemoved
boolean

Whether the "Powered by Bitrix24" label is hidden.

Possible values:

• true — the label is hidden
• false — the label is shown

If the plan does not allow removing the label, the value true is saved as false without an error

Yes

Name
type

Description

Write

entityScheme
integer

CRM scheme — the objects created by submitting the form, for example a lead or a deal with a contact. crm.form.configuration.get returns the scheme identifiers in the entitySchemes key.

The scheme determines which CRM fields can be added to the form

Required on creation

duplicateMode
string

What to do if the customer already exists in CRM.

Possible values from the duplicateModes key of crm.form.configuration.get:

• MERGE — merge data
• REPLACE — replace data

Yes

dealCategoryId
integer

Deal pipeline. 0 — the general pipeline, null — no pipeline specified. crm.form.configuration.get returns the pipeline identifiers in the dealCategories key

Yes

dealDuplicateControlEnabled
boolean

Duplicate control for deals.

Possible values:

• true — control is enabled
• false — control is disabled

Yes

smartProcessCategoryId
integer

SPA pipeline. crm.form.configuration.get returns the pipeline identifiers in the smartProcesses[].categories key

Yes

smartProcessDuplicateControlEnabled
boolean

Duplicate control for SPA items.

Possible values:

• true — control is enabled
• false — control is disabled

Yes

Name
type

Description

Write

name
string

Field code, for example LEAD_NAME. crm.form.entityfield.list returns the CRM field codes. The field must belong to the objects of the crm.entityScheme scheme. A code can appear in the form only once

Yes

type
string

Field type, for example string, phone, email. crm.form.configuration.get returns the list of types in the fieldTypes key.

Fields with choice options and products cannot be added via REST yet: list, checkbox, radio, product, booking. Such fields created in the interface are retained on write if their type is not changed

Yes

label
string

Field label

Yes

sort
integer

Field order. Calculated from the element's position in the fields array

Read-only

required
boolean

Whether the field is required.

Possible values:

• true — the field is required
• false — the field is optional

Yes

multiple
boolean

Whether multiple values can be entered.

Possible values:

• true — multiple values
• false — a single value

Yes

placeholder
string

Hint shown inside an empty field

Yes

valueType
string

Value type for contact fields, for example a work or mobile phone

Yes

value
string

Default value

Yes

Name
type

Description

logic
string

How the group's rules are combined.

Possible values:

• and — all rules must be met
• or — one rule is enough

rules
array

Group rules. A group must contain at least one rule. Each rule contains the condition and action objects

rules[].condition.fieldName
string

Code of the form field the rule tracks. The field must be in fields of this form

rules[].condition.event
string

Field event. Possible value: change — the value has changed

rules[].condition.operation
string

Comparison.

Possible values:

• = — equal to
• != or <> — not equal to
• >, >=, <, <= — greater than, greater than or equal to, less than, less than or equal to — for numeric fields
• empty — not filled in
• any — filled in
• contain — contains — for string fields
• !contain — does not contain — for string fields

rules[].condition.value
string

Value to compare with

rules[].action.fieldName
string

Code of the form field the rule acts on

rules[].action.type
string

Action.

Possible values:

• show — show the field
• hide — hide the field

rules[].action.value
string

Action value

Name
type

Description

entityName
string

CRM object, for example LEAD

fieldName
string

Object field code

value
string

Value the form writes to the field

Name
type

Description

userIds
integer[]

Identifiers of the responsible persons in queue order. An identifier cannot be repeated. User identifiers can be retrieved with user.get

checkWorkTime
boolean

Whether to take working hours into account when choosing the next responsible person.

Possible values:

• true — take into account
• false — do not take into account

Name
type

Description

enabled
boolean

Whether to show consents in the form.

Possible values:

• true — show
• false — do not show

items
array

Consents. Each element contains:

• agreementId — consent identifier
• checked — whether the consent is pre-selected
• required — whether the consent must be accepted

Name
type

Description

success
object

Result of a successful submission: url — redirect URL, text — message text. If both url and the refill option are set, the URL takes priority

failure
object

Result of a failed submission: url — redirect URL, text — message text

redirectDelay
integer

Delay before the redirect after a successful submission, from 0 to 10 seconds

refill
object

Offer to fill in the form again: enabled — whether the offer is enabled, caption — button text

Name
type

Description

enabled
boolean

Whether payment is enabled. Payment can be enabled if orders are available in Bitrix24

disabledPaySystemsId
integer[]

Payment systems the form does not offer. All other Bitrix24 payment systems are available, including those connected later. An empty array enables all payment systems. crm.form.configuration.get returns the identifiers in the paySystems key

Name
type

Description

enabled
boolean

Whether callback is enabled. It can be enabled if callback is available in Bitrix24

from
string

Number Bitrix24 uses to call the customer back. The number must be among the Bitrix24 telephony numbers

text
string

Text the customer hears during the call

Name
type

Description

googleAnalyticsId
string

Google Analytics identifier

googleAnalyticsPageViewEnabled
boolean

Whether to send page views to Google Analytics

yandexMetricaId
string

Web analytics counter identifier

Name
type

Description

whatsAppEnabled
boolean

Whether the form is enabled in the messenger. It can be enabled if the feature is available in Bitrix24

ads
array

Links to advertising service forms. Each element contains:

• direction — exchange direction
• providerCode — advertising service code
• accountId and accountName — advertising account identifier and name
• formId and formName — identifier and name of the form in the advertising service
• fieldMappings — field mapping: crmFieldName — CRM field, adsFieldName — advertising form field

Name
type

Description

entitySchemes
object[]

CRM object creation schemes: which objects a submitted form creates (detailed description).

The scheme identifier is passed in the crm.entityScheme field when creating and updating a form

duplicateModes
object[]

Modes for handling repeated form submissions: elements with the id and name fields.

The id value is passed in the crm.duplicateMode field. On a test Bitrix24, MERGE — merge and REPLACE — replace are returned

lead
object

Object with the enabled field of the boolean type:

• true — leads are enabled in CRM
• false — CRM works in simple mode without leads

dealCategories
object[]

Deal pipelines: elements with the id and name fields.

The id value is passed in the crm.dealCategoryId field. The general pipeline has the identifier 0

smartProcesses
object[]

SPAs whose items the form can create (detailed description)

languages
object[]

Form languages: elements with the id and name fields.

The id value is passed in the languageId field

currencies
object[]

Bitrix24 currencies (detailed description)

fieldTypes
object[]

Field types a form can be built from (detailed description).

The id value is passed in the fields[].type field

paySystems
object[]

Payment systems that can be used to pay for a submitted form: elements with the id and name fields.

The identifiers of the systems the form must not offer are passed in the payment.disabledPaySystemsId field. If the sale module is not installed in Bitrix24, the array is empty

permissions
object

Current user's permissions for CRM forms:

• canRead — can view forms
• canEdit — can create, update, and delete forms

limits
object

Object with the activeForms field — the active forms limit:

• current — how many forms are currently active
• maximum — how many forms can be kept active on the plan

If the number of active forms in Bitrix24 is unlimited, activeForms is null

product
object

Product information:

• isCloud — cloud Bitrix24

region
string

Bitrix24 region code, for example en

Name
type

Description

id
integer

Scheme identifier

name
string

Scheme name

description
string

Scheme description: which objects it creates

entityNames
string[]

Codes of the CRM objects the scheme creates, for example LEAD, CONTACT, COMPANY, DYNAMIC_174.

The codes are passed in the filter of crm.form.entityfield.list to retrieve the fields for the form

mainEntityName
string

Code of the scheme's main object. For the "Client" scheme — null

hasInvoice
boolean

Flag indicating that the scheme creates an invoice

dynamic
boolean

SPA scheme flag

Name
type

Description

entityTypeId
integer

SPA type identifier

entityName
string

SPA code, for example DYNAMIC_177

name
string

SPA name

categories
object[]

SPA pipelines: elements with the id and name fields.

The id value is passed in the crm.smartProcessCategoryId field

Name
type

Description

id
string

Currency code, for example EUR

fullName
string

Currency name

formatString
string

Amount output template, # is replaced with the amount

Name
type

Description

id
string

Form field type code, for example string, phone, email, section, hr

name
string

Field type name

parameters
string[]

Parameters that can be set for a field of this type in the fields[] element, for example label, required, multiple, placeholder, valueType, value. For the hr and br separators, the array is empty

Name
type

Description

id
string

Scenario code, for example callback, contacts, event_registration

title
string

Scenario name

description
string

Scenario description or null

categoryId
string

Scenario category code. crm.form.scenariocategory.list returns the category names

iconUrl
string

Path to the scenario icon in Bitrix24, or null if there is no icon

sections
string[]

Builder sections the scenario opens for setup, for example fields, agreements, crm, design

expertSections
string[]

Builder sections the scenario opens in advanced mode. Can be empty

defaultSection
string

Section the builder opens with, or null

openable
boolean

Flag indicating that the scenario opens the form builder.

Possible values:

• true — the scenario opens the builder
• false — the scenario does not open the builder but performs an action from actions

soon
boolean

Announced scenario flag.

Possible values:

• true — the scenario is announced but not available yet
• false — the scenario is available

actions
string[]

Additional scenario actions, for example showHelp or check. For most scenarios, the array is empty

Name
type

Description

id
string

Category code. Matches the categoryId field of a scenario from crm.form.scenario.list

title
string

Category name

Name
type

Description

name
string

Field code, for example CONTACT_NAME. Passed in fields[].name when creating or updating a form

label
string

Field name

type
string

Field type, for example string, typed_string, list, date, file, address. Fields of the list and checkbox types cannot be added to a form via REST

required
boolean

Required field flag in CRM

multiple
boolean

Multiple field flag

entityName
string

Code of the CRM object the field belongs to

entityLabel
string

CRM object name

items
object[]

Value options of a list field: elements with the fields id — the value saved in CRM, and label — the option name. For other fields, the array is empty

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. It can be activated with crm.form.activate

resourcesReady
boolean

Whether the form files are built for publishing.

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. The option has no settings, so settings and options are null, detailed description

click
object

Option for showing the form on a button or link click, detailed description

auto
object

Option for showing the form automatically after a specified time, detailed description

Name
type

Description

code
string

HTML code for embedding on a website. null until the form files are built

previewUrl
string

Link to the form preview in this placement option

settings
object

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

options
object

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

Name
type

Description

type
string

Form window type.

Possible values:

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

position
string

Horizontal window position.

Possible values:

• left — left
• center — center
• right — right

vertical
string

Vertical window position.

Possible values:

• bottom — bottom
• top — top

delay
integer

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

button
object

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

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. The allowed values are listed in click.options.button.font, for example modern, classic, elegant

align
string

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

plain
boolean

Flag for a button without a background.

Possible values:

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

rounded
boolean

Rounded corners flag.

Possible values:

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

outlined
boolean

Button outline flag.

Possible values:

• true — the button has an outline
• false — 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

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. Available only for the auto option

button
object

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

Name
type

Description

variant
string

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

code
string

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

url
string

Public link to the form. Returned for the link option

Name
type

Description

formId
integer

CRM form identifier from the request filter

id
integer

Widget identifier

name
string

Widget name

system
boolean

System widget flag.

Possible values:

• true — the widget was created by Bitrix24 automatically
• false — the widget was created by a user

bound
boolean

Whether the form from the filter is connected to this widget.

Possible values:

• true — the form is in an active widget slot
• false — the form is not connected to the widget

formsId
integer[]

Identifiers of all CRM forms connected to the widget

previewUrl
string

Link to the widget preview. The form from the filter is visible in the preview only if bound is true

Name
type

Description

formId
integer

CRM form identifier from the request filter

id
integer

Open Channel identifier

name
string

Open Channel name

bound
boolean

Whether the form from the filter is the welcome form of this Open Channel.

Possible values:

• true — the form is set as the welcome form
• false — the form is not set as the welcome form

welcomeFormEnabled
boolean

Whether a welcome form is enabled in the Open Channel: this one or another.

Possible values:

• true — the welcome form is enabled
• false — the welcome form is disabled

welcomeFormId
integer

Identifier of the Open Channel welcome form. null if no form is selected

welcomeFormDelayed
boolean

When the welcome form is shown.

Possible values:

• true — after the visitor's first message
• false — before the visitor's first message

previewUrl
string

Link to the preview of the website widget with this Open Channel. null if the Open Channel is not connected to any active widget. The form from the filter is visible in the preview only if bound is true