Skip to content

data-types.md

Latest commit

 

History

History
553 lines (475 loc) · 24.8 KB

data-types.md

File metadata and controls

553 lines (475 loc) · 24.8 KB
Raw

Data Types and Object Structure in the CRM REST API

{% 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 %}

{% if build == 'dev' %}

{% note alert "TO-DO not exported to prod" %}

  • Create links with catalog_product.id and catalog_measure.code to the directory when it becomes available.

{% endnote %}

{% endif %}

Basic data types are listed in a separate article.

In this article, we will discuss the data types and object structures specific to CRM.

Data Types

#| || Type | Descriptions and Values || || crm_status | String identifier of a CRM directory element (e.g., NEW). Possible values for a specific directory can be obtained using the method crm.status.list with a filter by ENTITY_ID. || || crm_lead | Integer identifier of a CRM lead. Information about the lead can be retrieved using the method crm.lead.get. || || crm_deal | Integer identifier of a CRM deal. Information about the deal can be retrieved using the method crm.deal.get. || || crm_contact | Integer identifier of a CRM contact. Information about the contact can be retrieved using the method crm.contact.get. || || crm_company | Integer identifier of a CRM company. Information about the company can be retrieved using the method crm.company.get. || || crm_quote | Integer identifier of a CRM estimate. Information about the estimate can be retrieved using the method crm.quote.get. || || crm_category | Integer identifier of a CRM sales funnel. Information about the funnel can be retrieved using the method crm.category.get. || || crm_entity| Integer identifier of an element of a certain CRM object. Fields of this type explicitly contain information about which CRM object they belong to. For example, fields like parentId{entityTypeId} contain the entity type identifier within their name. Information about the element can be retrieved using the method crm.item.get by passing entityTypeId from the field name and id from its value. || || lang_map | Object format:

{
    lang_1: value_1,
    lang_2: value_2,
    ..
    lang_n: value_n,
}

where lang_n - Language identifier value_n - Value for language lang_n || || crm_dynamic_type.id | Integer identifier of a smart process. Identifiers can be obtained using the method crm.type.list. || || crm_userfield | Value of a user field. The specific type of the value depends on the type of the field itself — see {#T}. || || userFieldEntityId | String code of the CRM object type to which the user field is bound. For example, CRM_CONTACT. The complete list of codes is in the section CRM Object Types. || || location | Integer identifier of a location from the Bitrix24 location directory. This is a service type: fields with it are not recommended for use, and in most objects they are marked as outdated. || || crm_item_product_row | Integer identifier of the product row of a CRM object. Product row identifiers can be obtained using the method crm.item.productrow.list. || || crm_multifield | Object describing a "multifield". Multifields are used to store phone numbers, email addresses, and other contact information. In leads, contacts, and companies, fields of this type are PHONE, EMAIL, WEB, and IM. || || crm_currency | Object describing currency. || || crm_currency_localization | Object describing currency localization. || || crm_orderentity | Object describing the connection between CRM and online store orders. || || recurring_params | Object with the parameters for calculating the next repetition date for a recurring CRM object template. The composition of the fields depends on the object and is described on the page of the specific method. For example, fields of the PARAMS object for recurring deals. || || type | Object describing a custom CRM object type (SPA). || || type.relations | Object containing relationships to other CRM entities. || || relation | Object describing a related CRM element. || || type.linkedUserFields | Object describing a set of fields in which the SPA should be displayed. || || diskfile | File retained on Bitrix24 Drive. In the response, the method returns an object describing the file; when writing, the value is passed as an upload structure. || || attached_diskfile | File attached to a timeline record. In the response, the method returns an object describing the file; when writing, the value is passed as an upload structure. || || product_file | Product image in the old product card. In the response, the method returns an object describing the file. || || crm_activity_binding | Object describing the binding of an activity to a CRM element. || || crm_activity_communication | Object describing the communication channel of an activity. The composition of the fields is in the article {#T}. || |#

Activity Enumerations {#activity-enums}

Activity fields reference service enumerations. The field value is an integer from a fixed set.

#| || Type | Values || || crm_enum_activitytype | Type of the activity: 1 — meeting, 2 — call, 3 — task, 4 — email, 5 — general type for importing calendar events, 6 — general type for activities managed by providers. 0 — type is not defined. || || crm_enum_activitystatus | Status of the activity: 1 — pending, 2 — completed, 3 — completed automatically. 0 — status is not defined. || || crm_enum_activitypriority | Importance of the activity: 1 — low, 2 — medium, 3 — high. 0 — not specified. || || crm_enum_activitynotifytype | Unit of time for the reminder: 1 — minutes, 2 — hours, 3 — days. 0 — reminder is not specified. || || crm_enum_activitydirection | Direction of the activity: 1 — incoming, 2 — outgoing. 0 — direction is not defined. Applies to calls and emails. || || crm_enum_contenttype | Format of the description text: 1 — plain text, 2 — BB codes, 3 — HTML. 0 — format is not defined. || || crm_enum_ownertype | Integer identifier of the CRM object type to which the record belongs. The possible values are returned by the method crm.enum.ownertype. || |#

Object Structure

crm_multifield {#crm_multifield}

#| || Value type | Description || || ID integer | Identifier of the multifield value. || || TYPE_ID string | Type of the multifield. Can take values PHONE, EMAIL, WEB, IM, LINK. || || VALUE string | String value of the multifield. || || VALUE_TYPE string | Type of the multifield value. Can take values WORK, MOBILE, FAX, HOME, PAGER, MAILING, OTHER for phone, WORK, HOME, MAILING, OTHER for email, WORK, HOME, VK, LIVEJOURNAL, TWITTER, OTHER for website, TELEGRAM, VK, SKYPE, VIBER, BITRIX24, OPENLINE, IMOL, ICQ, MSN, JABBER, OTHER for messenger. || |#

crm_item_product_row

#| || Value type | Description || || id integer | Identifier of the product row. || || ownerId integer | Identifier of the CRM object. || || ownerType string | Identifier of the CRM object type. || || productId catalog_product.id | Identifier of the product from the catalog. || || productName string | Name of the product in the product row. || || price double | Price per unit of the product row, including discounts and taxes. || || priceAccount double | Price per unit of the product row, including discounts and taxes, converted to the reporting currency. || || priceExclusive double | Price per unit of the product row, including discounts but excluding taxes. || || priceNetto double | Price per unit of the product row excluding discounts and taxes. || || priceBrutto double | Price per unit of the product row including taxes but excluding discounts. || || quantity double | Quantity of the product. || || discountTypeId integer | Type of discount. Possible values:

  • 1 — absolute value
  • 2 — percentage value. || || discountRate double | Discount value in percentage. || || discountSum double | Absolute discount value. || || taxRate double | Tax rate in percentage. || || taxIncluded string | Indicator of whether tax is included in the price. Possible values:
  • Y – tax included
  • N – tax not included. || || customized string | Deprecated. || || measureCode catalog_measure.code | Unit of measure code. || || measureName string | Text representation of the unit of measure (e.g., pcs, kg, m, l, etc.). || || sort integer | Sorting. || || xmlId string | External identifier of the product row. || || type integer | Type of product. Possible values:
  • 1 - Simple product
  • 2 - Bundle
  • 3 - Product with trade offers
  • 4 - Trade offer
  • 5 - Trade offer without a product (not specified or deleted)
  • 6 - Specific type indicating an invalid product with trade offers
  • 7 — Service. || || storeId integer | Identifier of the warehouse. || |#

crm_currency

#| || Value type | Description || || AMOUNT double | Exchange rate relative to the base currency. For the base currency, it is always equal to 1. Precision — 4 decimal places. || || AMOUNT_CNT integer | Nominal value. For the base currency, it is always equal to 1. || || BASE string | Indicator of whether the currency is base (Y/N). || || CURRENCY string | Currency identifier. Corresponds to ISO 4217 standard. || || DATE_UPDATE datetime | Date of the last change. || || SORT integer | Sorting. || || LID string | Language code for which the localization parameters are returned. || || DECIMALS integer | Number of decimal places for the fractional part (localization parameter). || || DEC_POINT string | Decimal point for output (localization parameter). || || FORMAT_STRING string | Format template (localization parameter). || || FULL_NAME string | Name of the currency (localization parameter). || || THOUSANDS_SEP string | Thousands separator (localization parameter). || || LANG object | Currency localizations. An object with a list of available localizations in the format {"lang_1": "value_1", ... "lang_N": "value_N"}, where lang_N is the language identifier, and value is an object of type crm_currency_localization. The language identifier is a string of two Latin letters. Possible values can be found in the table of language identifiers. || |#

crm_currency_localization

#| || Value type | Description || || DECIMALS integer | Number of decimal places for the fractional part.

Default value — 2. || || DEC_POINT string | Decimal point for output.

Default value — . (dot symbol). || || FORMAT_STRING string | Format template. Must contain the symbol # — the value will be substituted in its place.

Default value — #.

Examples of templates for the amount 1000:

  • $ # — $ 1000
  • # rub. — 1000 rub.
  • € # — € 1000. || || FULL_NAME string | Name of the currency.

Default value — crm_currency.CURRENCY. || || HIDE_ZERO string | Indicator of whether to hide insignificant zeros (Y/N).

Default value — N. || || THOUSANDS_SEP string | Thousands separator.

Default value — (space). || || THOUSANDS_VARIANT string | Code for the thousands separator.

Default value — S.

When creating or modifying localization, if a value is specified for the THOUSANDS_VARIANT field, the value in THOUSANDS_SEP will be ignored and replaced according to the list:

  • N — empty, no thousands separator. Example: 12345678
  • C — comma. Example: 12,345,678
  • D — dot. Example: 12.345.678
  • S — space. Example: 12 345 678
  • B — non-breaking space. Example: 12 345 678 Differs from the previous option in that when line breaks occur, the result is not split into parts.

If a thousands separator is not needed, the THOUSANDS_VARIANT field must be explicitly passed with the value N. An empty string in the THOUSANDS_SEP field is not allowed. || |#

crm_orderentity

#| || Value type | Description || || OWNER_ID integer | Identifier of the CRM object. || || OWNER_TYPE_ID integer | Identifier of the CRM object type. || || ORDER_ID sale_order.id | Identifier of the order. || |#

type

#| || Value type | Description || || id integer | Identifier of the SPA. || || title string | Title of the SPA. || || code string | Symbolic code. || || createdBy integer | Identifier of the user who created this SPA. || || entityTypeId integer | Identifier of the entity type. || || isCategoriesEnabled boolean | Are custom funnels and sales tunnels enabled? || || isStagesEnabled
boolean | Is the use of custom stages and Kanban enabled? || || isBeginCloseDatesEnabled boolean | Are the Start Date and End Date fields enabled? || || isClientEnabled
boolean | Is the Client field enabled? || || isUseInUserfieldEnabled boolean | Is the use of the SPA in the user field enabled? || || isLinkWithProductsEnabled boolean | Is the linking of catalog products enabled? || || isMycompanyEnabled boolean | Is the Your Company Details field enabled? || || isDocumentsEnabled boolean | Is document printing enabled? || || isSourceEnabled
boolean | Are the Source and Additional Information about Source fields enabled? || || isObserversEnabled boolean | Is the Observers field enabled? || || isRecyclebinEnabled boolean | Is the use of the recycle bin enabled? || || isAutomationEnabled boolean | Are Automation rules and triggers enabled? || || isBizProcEnabled
boolean | Is the use of the business process designer enabled? || || isSetOpenPermissions
boolean | Should new funnels be made available to everyone? || || isPaymentsEnabled
boolean | System field indicating whether the payment option is enabled. || || isCountersEnabled
boolean | System field indicating whether counters are enabled. || || createdTime datetime | System field indicating the creation time of the SPA. || || updatedTime datetime | System field indicating the last modification time of this SPA. || || updatedBy integer | Identifier of the user who modified this SPA. || || relations object | Object containing relationships to other CRM entities. || || linkedUserFields
object | Set of fields in which this SPA should be displayed. || || customSections array | List of all digital workplaces.

This parameter is deprecated. For working with digital workplaces, use the methods crm.automatedsolution.*. || || customSectionId integer | Identifier of the digital workplace.

This parameter is deprecated. For working with digital workplaces, use the methods crm.automatedsolution.*. || |#

type.relations

#| || Value type | Description || || parent relation[] | CRM elements that will be linked to this SPA. || || child
relation[] | CRM elements to which this SPA will be linked. || |#

relation

#| || Value type | Description || || entityTypeId
integer | Identifier of the system or user-defined type of the CRM object. || || isChildrenListEnabled boolean | Should the related element be added to the card? || || isPredefined
boolean | Is this relationship predefined (system)? || |#

type.linkedUserFields

#| || Value type | Description || || CALENDAR_EVENT|UF_CRM_CAL_EVENT boolean | Calendar event. || || TASKS_TASK|UF_CRM_TASK boolean | Tasks. || || TASKS_TASK_TEMPLATE|UF_CRM_TASK boolean | Task templates. || |#

diskfile {#diskfile}

File retained on Bitrix24 Drive. In the response, the method returns an object describing the file.

#| || Name type | Description || || ID integer | Identifier of the file on Drive. || || FILE_ID integer | Identifier of the file in the file storage. || || NAME string | Name of the file. || || SIZE string | Size of the file in a readable form. For example, 43 Kb. || || BYTES integer | Size of the file in bytes. || || CAN_READ boolean | Is the file available for reading by the current user? || || VIEW_URL string | Address for viewing or downloading the file. || || PREVIEW_URL string | Address of the preview. It is filled in only for images and videos; in other cases, it is an empty string. || |#

To write a value into a field of this type, pass the file upload structure according to the rules for working with files.

attached_diskfile {#attached_diskfile}

File attached to a timeline record. It differs from diskfile in that the file is not retained in the CRM object but is bound to the record as an attachment.

In the response, the method returns an object describing the file: identifier of the attachment, date, type, name, size and — for images — the dimensions of the image.

To write a value, pass the file upload structure according to the rules for working with files.

crm_activity_binding {#crm_activity_binding}

Binding of an activity to a CRM element. The field is multiple and read-only.

#| || Name type | Description || || OWNER_TYPE_ID crm_enum_ownertype | Type of the CRM object to which the activity is bound. || || OWNER_ID integer | Identifier of the CRM element to which the activity is bound. || |#

Language Identifiers for Bitrix24 {#lang-ids}

#| || Language Identifier | Language || || ar | Arabic || || br | Portuguese (Brazil) || || de | German || || en | English || || fr | French || || hi | Hindi || || id | Indonesian || || it | Italian || || ja | Japanese || || la | Spanish || || ms | Malay || || pl | Polish || || ru | Russian || || sc | Chinese || || tc | Chinese (Taiwan) || || th | Thai || || tr | Turkish || || ua | Ukrainian || || vn | Vietnamese || |#

Objects Used in Responses

Description of a Single Field crm_rest_field_description {#crm_rest_field_description}

#| || Name type | Description || || type string | Type of the field. || || isRequired boolean | Is the field required? || || isReadOnly boolean | Is the field read-only? || || isImmutable boolean | Indicator of whether the field value can only be filled once when creating a new element. || || isMultiple boolean | Indicator of whether the field is multiple. If true, values in the field are passed as an array. || || isDynamic boolean | Is the field user-defined? || || title string | Name of the field. || || upperName string | Name of the field in uppercase. || |#

Description of User Field Type Address {#crm_user_field_address}

The user field of type "Address" stores data in a single line. The table provides a description of the components of this line. A detailed description of the components of an address can be found in the article About Addresses.

#| || Name type | Description | Example || || ADDRESS_1 string | Street, house number | 350 5th Avenue || || ADDRESS_2 string | Apartment, office, room, floor | Suite 120 || || POSTAL_CODE string | Postal code | 10118 || || CITY string | Settlement | New York || || REGION string | District | Manhattan || || PROVINCE string | Region | New York || || COUNTRY string | Country | US || || LATITUDE string | Latitude coordinates | 40.748441 || || LONGITUDE string | Longitude coordinates | -73.985664 || || LOC_ADDR_ID string | Location address identifier | 8842193 || |#

CRM Object Types {#object_type}

#| || Object Type | Numeric Identifier of the Type entityTypeId | Symbolic Code of the Type entityTypeName | Short Symbolic Code of the Type entityTypeAbbr | User Field Object Type userFieldEntityId || || Lead | 1 | LEAD | L | CRM_LEAD || || Deal | 2 | DEAL | D | CRM_DEAL || || Contact | 3 | CONTACT | C | CRM_CONTACT || || Company | 4 | COMPANY | CO| CRM_COMPANY || || Invoice (old) | 5 | INVOICE | I | CRM_INVOICE || || Invoice (new) | 31 | SMART_INVOICE | SI | CRM_SMART_INVOICE || || Estimate | 7 | QUOTE | Q | CRM_QUOTE || || Requisite | 8 | REQUISITE | RQ | CRM_REQUISITE || || Order | 14 | ORDER | O | ORDER || || SPA | 128 | DYNAMIC_128 | T80 | CRM_1 || |#

{% note warning "" %}

For new integrations, use the "Invoice (new)" with entityTypeId = 31 (SMART_INVOICE). The type INVOICE with entityTypeId = 5 is retained for compatibility with the old invoice functionality and is not recommended for new projects.

{% endnote %}

Format of Values for User Field "Binding to CRM Elements" {#crm-binding-format}

User fields of type crm accept values in the format {PREFIX}_{ID}, where PREFIX is the short symbolic code of the type (entityTypeAbbr) from the table above, and ID is the numeric identifier of the element.

Single Binding — string:

#| || Object Type | Example Value || || Lead | L_4 || || Deal | D_1 || || Contact | C_2 || || Company | CO_3 || || Invoice (new) | SI_7 || || SPA | T80_6 || |#

Multiple Binding (field with isMultiple: true) — array of strings:

["C_123", "CO_456"]

For SPAs, the PREFIX is calculated from entityTypeId: the value is converted to hexadecimal representation in lowercase, then the prefix T is added. Example: entityTypeId = 128 → 80 → PREFIX T80.