Data Types and Object Structure in the CRM REST API
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
In addition to the basic types, fields of CRM methods in the previous API version use CRM types: identifiers of items and directory entries, multifields, files, addresses, and object type codes. The field type is specified in the type key, which is returned by field retrieval methods such as crm.item.fields. The response format is described in the Field Description section.
Use this reference when:
- a field has a CRM type, such as
crm_status,crm_multifield, orcrm_entity - you need the numeric or symbolic code of a CRM object type
- you need to build a value to write: a binding to a CRM item, an activity file or a timeline comment file, or an address
This reference describes the types of the previous API version — the crm.deal.*, crm.item.*, and other methods called at /rest/. The value formats of the Bind To CRM Items and Address user fields are described for both versions.
- For new integrations, use REST 3.0 — its methods are called at
/rest/api/. Many methods have kept their names, such ascrm.deal.get; equivalents for the rest are listed in Migrating to the New CRM Methods. - Currencies, SPA types, the timeline, and some other methods are available only in the previous version for now. See the list in the What REST 3.0 Does Not Support Yet section.
- REST 3.0 describes fields differently: the field type is returned by crm.<type>.field.list, and the field sets are listed on the object pages, for example Contact Fields in REST 3.0.
- Both versions use the numeric
entityTypeIdidentifiers from the CRM Object Type table and the language identifiers. The shortentityTypeAbbrcodes are used only in the previous version. REST 3.0 does not acceptuserFieldEntityIdcodes — the method name defines the object type — but returns them in theentityIdfield of the crm.<type>.field.custom.* methods.
Described in other articles:
- the basic types
integer,string,datetime,boolean, and others — in Data Types and Parameter Formats in REST API; compound notations such astype[]— in the How Compound Types Are Written section - CRM form types
crm_form*— in Data Types and Object Structure in the CRM Forms REST API
The object.field notation, such as catalog_product.id, means the value of the id field of the catalog_product object.
Data Types
|
Type |
Description |
|
|
String identifier of a CRM directory entry (e.g., In REST 3.0:
|
|
|
Integer identifier of a CRM lead. To retrieve the lead: crm.lead.get in REST 3.0 or crm.lead.get in the Previous Version |
|
|
Integer identifier of a CRM deal. To retrieve the deal: crm.deal.get in REST 3.0 or crm.deal.get in the Previous Version |
|
|
Integer identifier of a CRM contact. To retrieve the contact: crm.contact.get in REST 3.0 or crm.contact.get in the Previous Version |
|
|
Integer identifier of a CRM company. To retrieve the company: crm.company.get in REST 3.0 or crm.company.get in the Previous Version |
|
|
Integer identifier of a CRM estimate. To retrieve the estimate: crm.quote.get in REST 3.0 or crm.quote.get in the Previous Version |
|
|
Integer identifier of a CRM pipeline. To retrieve the pipeline: crm.<type>.category.get in REST 3.0 or crm.category.get in the Previous Version |
|
|
Integer identifier of a CRM item. The object type is returned in the
|
|
|
Object in the following format:
where:
|
|
|
Integer identifier of an SPA — the |
|
|
Value of a user field. This is how the type is written in the field tables on the |
|
|
String code of the CRM object type to which the user field is bound. For example, |
|
|
String identifier of a location from the Bitrix24 location directory. A service type used to calculate taxes by location: fields of this type, such as |
|
Product item object of a CRM item. The structure in the previous version is in the crm_item_product_row section, and in REST 3.0 — in the Product Item Fields section. The item identifier is written as |
|
|
Object describing a "multifield". Multifields store phone numbers, email addresses, and other contact information in leads, contacts, companies, and SPAs with |
|
|
CRM currency. In object fields, such as |
|
|
Object describing currency localization. In the crm.currency.fields response, the field with these objects has the |
|
|
Object describing the link between a CRM item and an online store order. Returned by the crm.orderentity.* methods |
|
|
|
Object with the parameters for calculating the next repetition date for a recurring CRM object template. The field set depends on the object and is described on the page of the specific method. For example, fields of the PARAMS object for recurring deals |
|
Object describing a custom CRM object type (SPA) |
|
|
Object with the links between an SPA and other CRM object types |
|
|
Object describing a single link between an SPA and a CRM object type |
|
|
Object with user fields of other modules in which SPA items can be selected |
|
|
File retained on Bitrix24 Drive |
|
|
File attached to a timeline comment |
|
|
|
Product image in the old product card — the |
|
|
Integer identifier of the CRM form through which the item was created. The form data is returned by the crm.form.get method |
|
|
Integer identifier of the repeat sale scenario that created the deal. Despite the type name, the field contains the identifier, not the scenario name. The |
|
Object describing the binding of an activity to a CRM item |
|
|
|
Object describing the communication channel of an activity. The field set is in Get Communication Description crm.activity.communication.fields. In REST 3.0, communication channels are returned in the |
Activity Enumerations
Activity fields in the crm.activity.* methods of the previous version reference service enumerations. The field value is an integer from a fixed set. In REST 3.0, activity fields work differently: the direction and the description format are passed as strings, such as incoming or html, and bindings as entityTypeId and entityId pairs. See the format in the Activity Fields section.
|
Type |
Values |
|
|
Type of the activity: |
|
|
Status of the activity: |
|
|
Importance of the activity: |
|
|
Unit of time for the reminder: |
|
|
Direction of the activity: |
|
|
Format of the description text: |
|
|
Integer identifier of the CRM object type to which the record belongs — the |
Object Structure
crm_multifield
The crm.lead.*, crm.contact.*, and crm.company.* methods return the keys in uppercase, as in the table. In the crm.item.* methods, the same data is returned in the fm field — see CRM Object Fields for details.
To write in the previous version, pass an array of objects to the field, for example PHONE:
- add a value —
VALUEandVALUE_TYPE - change a value —
ID, the newVALUE, andVALUE_TYPE. WithoutVALUE_TYPE, the type is reset toWORK, or toOTHERforIM - delete a value —
IDandDELETE: "Y"or an emptyVALUE
See examples on the crm.contact.update page.
In REST 3.0, phone numbers, email, websites, and messengers are separate fields phone, email, web, and im; their format is described in the Phone Numbers, Email, Websites, and Messengers section.
|
Value |
Description |
|
ID |
Identifier of the multifield value |
|
TYPE_ID |
Type of the multifield: |
|
VALUE |
String value of the multifield |
|
VALUE_TYPE |
Type of the multifield value. The possible values depend on
|
crm_item_product_row
Product item of a CRM item in the crm.item.productrow.* methods of the previous version. In REST 3.0, the item fields are different, for example ownerTypeId instead of ownerType — see Product Item Fields.
|
Value |
Description |
|
id |
Identifier of the product item |
|
ownerId |
Identifier of the CRM object |
|
ownerType |
Short symbolic code of the CRM object type — a value from the |
|
productId |
Identifier of the product from the catalog |
|
productName |
Name of the product in the product item |
|
price |
Price per unit of the product item, including discounts and taxes |
|
priceAccount |
Price per unit of the product item, including discounts and taxes, converted to the reporting currency |
|
priceExclusive |
Price per unit of the product item, including discounts but excluding taxes |
|
priceNetto |
Price per unit of the product item, excluding discounts and taxes |
|
priceBrutto |
Price per unit of the product item, including taxes but excluding discounts |
|
quantity |
Quantity of the product |
|
discountTypeId |
Type of discount.
|
|
discountRate |
Discount value in percent |
|
discountSum |
Absolute discount value |
|
taxRate |
Tax rate in percent. Returns |
|
taxName |
Name of the tax rate. For example, |
|
taxIncluded |
Indicator of whether tax is included in the price.
|
|
customized |
Deprecated field. Always |
|
measureCode |
Unit of measure code |
|
measureName |
Text representation of the unit of measure. For example, pcs, kg, m, l |
|
sort |
Sorting |
|
xmlId |
External identifier of the product item |
|
type |
Type of product.
|
|
storeId |
Identifier of the warehouse. Filled in only if the product item has a reservation; otherwise, |
crm_currency
Currency in the response of the crm.currency.get and crm.currency.list methods.
|
Value |
Description |
|
AMOUNT |
Exchange rate relative to the base currency. |
|
AMOUNT_CNT |
Nominal value. |
|
BASE |
Indicator of whether the currency is the base one ( |
|
CURRENCY |
Currency identifier. Corresponds to the ISO 4217 standard |
|
DATE_UPDATE |
Date of the last change |
|
SORT |
Sorting |
|
LID |
Language code for which the localization parameters are returned |
|
DECIMALS |
Number of decimal places in the fractional part |
|
DEC_POINT |
Decimal point for output |
|
FORMAT_STRING |
Format template |
|
FULL_NAME |
Name of the currency |
|
THOUSANDS_SEP |
Thousands separator |
|
LANG |
Currency localizations. The value for each language is a crm_currency_localization object |
crm_currency_localization
Currency output parameters for one language. You can manage them with the crm.currency.localizations.* methods.
|
Value |
Description |
|
DECIMALS |
Number of decimal places in the fractional part. Default value — |
|
DEC_POINT |
Decimal point for output. Default value — |
|
FORMAT_STRING |
Format template. Must contain the Examples of templates for the amount 1000:
|
|
FULL_NAME |
Name of the currency. If the name is not set, the |
|
HIDE_ZERO |
Indicator of whether to hide insignificant zeros ( Default value — |
|
THOUSANDS_SEP |
Thousands separator. Default value — |
|
THOUSANDS_VARIANT |
Code of the thousands separator. Default value — If you pass a non-empty
If you do not need a thousands separator, pass the Pass a custom separator in |
crm_orderentity
Link between a CRM item and an order in the crm.orderentity.* methods.
|
Value |
Description |
|
ownerId |
Identifier of the CRM object |
|
ownerTypeId |
Numeric identifier of the CRM object type — a value from the |
|
orderId |
Identifier of the order |
type
SPA in the crm.type.* methods. The is* flags are returned as Y or N.
|
Value |
Description |
|
id |
Identifier of the SPA |
|
title |
Title of the SPA |
|
code |
Symbolic code |
|
createdBy |
Identifier of the user who created the SPA. Read-only |
|
entityTypeId |
Numeric identifier of the CRM object type, |
|
isCategoriesEnabled |
Whether custom pipelines and sales tunnels are enabled |
|
isStagesEnabled |
Whether custom stages and the Kanban board are enabled |
|
isBeginCloseDatesEnabled |
Whether the Start Date and End Date fields are enabled |
|
isClientEnabled |
Whether the Client field is enabled |
|
isUseInUserfieldEnabled |
Whether the SPA can be used in user fields |
|
isLinkWithProductsEnabled |
Whether linking catalog products is enabled |
|
isMycompanyEnabled |
Whether the Your Company Details field is enabled |
|
isDocumentsEnabled |
Whether document printing is enabled |
|
isSourceEnabled |
Whether the Source and Source Information fields are enabled |
|
isObserversEnabled |
Whether the Observers field is enabled |
|
isRecyclebinEnabled |
Whether the recycle bin is enabled |
|
isAutomationEnabled |
Whether automation rules and triggers are enabled |
|
isBizProcEnabled |
Whether the workflow designer is enabled |
|
isSetOpenPermissions |
Whether new pipelines are made available to everyone |
|
isRecurringEnabled |
Whether the Recurrence field is enabled |
|
isMultifieldsEnabled |
Whether communication fields are enabled: phone, email, and others |
|
isStartCatalogEnabled |
Whether the process launch catalog is enabled |
|
isCreateByFormEnabled |
Whether creating items through a CRM form is enabled |
|
startCatalogFormId |
Identifier of the CRM form for creating items. If no form is set — |
|
daysBeforeClose |
Number of days from creation allotted to an item before completion. If no deadline is set — |
|
isPaymentsEnabled |
Whether payments are enabled. Read-only |
|
isCountersEnabled |
Whether counters are enabled. Read-only |
|
isInitialized |
Whether the SPA creation is complete. The value |
|
createdTime |
Time the SPA was created. Read-only |
|
updatedTime |
Time the SPA was modified. Read-only |
|
updatedBy |
Identifier of the user who modified the SPA. Read-only |
|
relations |
Links between the SPA and other CRM object types |
|
linkedUserFields |
User fields of other modules in which SPA items can be selected |
|
customSections |
List of all digital workplaces The field is deprecated. To work with digital workplaces, use the |
|
additionalCustomSectionIds |
Identifiers of additional digital workplaces in which the SPA is displayed |
|
customSectionId |
Identifier of the digital workplace The field is deprecated. To work with digital workplaces, use the |
type.relations
Links of an SPA — the relations field of the type object.
|
Value |
Description |
|
parent |
CRM object types that can be parents of the SPA |
|
child |
CRM object types for which the SPA can be a parent |
relation
A single link from the parent and child arrays. The is* flags are returned as Y or N.
|
Value |
Description |
|
entityTypeId |
Numeric identifier of the CRM object type |
|
isChildrenListEnabled |
Whether to show the list of child items in the parent card. When writing in crm.type.add and crm.type.update, pass the string |
|
isPredefined |
Whether the link is predefined (system) |
type.linkedUserFields
User fields of other modules in which SPA items can be selected — the linkedUserFields field of the type object. Bitrix24 retains it only if isUseInUserfieldEnabled is turned on for the SPA.
- The key is a string in the
{field object}|{field code}format, for exampleTASKS_TASK|UF_CRM_TASK. This is a single key; the|character does not split it. - The value in the response is
Yif SPA items can be selected in this field, andNif they cannot.
|
Value |
Description |
|
CALENDAR_EVENT|UF_CRM_CAL_EVENT |
Calendar event |
|
TASKS_TASK|UF_CRM_TASK |
Tasks |
|
TASKS_TASK_TEMPLATE|UF_CRM_TASK |
Task templates |
The boolean type in the table describes the response: Y or N. When writing in crm.type.add and crm.type.update, pass only the string "true" — any other value, including Y, turns the field off.
diskfile
Activity file retained on Bitrix24 Drive. This type is used by the FILES field and the deprecated WEBDAV_ELEMENTS field in the crm.activity.* methods. The field is multiple: the response contains an array of objects. In REST 3.0, activity files are returned in the files field with the keys id, name, url, and downloadUrl; see the Activity Fields section for details.
|
Value |
Description |
|
id |
Identifier of the file |
|
url |
Address for downloading the file |
To write a value to a field of this type, pass the file upload structure according to the rules for working with files.
attached_diskfile
File attached to a timeline comment — the FILES field in the crm.timeline.comment.* methods.
In the response, the field is an object whose keys are file identifiers on Drive and whose values are file descriptions:
|
Value |
Description |
|
id |
Identifier of the file on Drive |
|
date |
Date the file was uploaded |
|
type |
Kind of file: |
|
name |
Name of the file |
|
size |
File size in bytes |
|
Image dimensions |
|
|
authorId |
Identifier of the user who uploaded the file |
|
authorName |
Name of the user who uploaded the file |
|
urlPreview |
Preview address. For files without a preview — |
|
urlShow |
Address for viewing an image. For other files, it matches |
|
urlDownload |
Address for downloading the file |
Example field value:
{
"11051": {
"id": 11051,
"date": "2026-11-10T15:20:58+01:00",
"type": "file",
"name": "check.txt",
"size": 5,
"image": false,
"authorId": 1,
"authorName": "Klaus Weber",
"urlPreview": null,
"urlShow": "https://example.bitrix24.com/disk/downloadFile/11051/?&ncc=1&filename=check.txt",
"urlDownload": "https://example.bitrix24.com/disk/downloadFile/11051/?&ncc=1&filename=check.txt"
}
}
The value is written the same way as for diskfile.
crm_activity_binding
Binding of an activity to a CRM item in the crm.activity.* methods of the previous version. The field is multiple and read-only. In REST 3.0, bindings are returned in the bindings field as entityTypeId and entityId pairs; see the Activity Fields section for details.
|
Value |
Description |
|
OWNER_TYPE_ID |
Type of the CRM object to which the activity is bound |
|
OWNER_ID |
Identifier of the CRM item to which the activity is bound |
Field Description
The crm_rest_field_description structure describes a single field in the response of field retrieval methods, such as crm.item.fields or crm.deal.fields. The response is an object where the key is the field code and the value is a description in this format. The is* flags are returned as JSON values true or false. In REST 3.0, the field description is structured differently; see its format on the crm.<type>.field.list page.
|
Value |
Description |
|
type |
Field type: a basic type, a CRM type from this reference, or a user field type |
|
isRequired |
Whether the field is required |
|
isReadOnly |
Whether the field is read-only. The value of such a field cannot be passed when creating or updating an item |
|
isImmutable |
Whether the field can be filled in only when creating an item. The value cannot be changed later |
|
isMultiple |
Whether the field is multiple. Values of a multiple field are passed as an array |
|
isDynamic |
Whether the field is a user field |
|
isDeprecated |
Deprecated field flag. Returned only for deprecated fields, with the value |
|
title |
Name of the field. In the methods of individual objects, such as |
|
upperName |
Field code in uppercase. Returned by the universal methods |
|
statusType |
Code of the directory that provides the field values. Returned for fields of the |
|
items |
Value options. Returned for user fields of the |
|
settings |
Field settings. The set depends on the field type |
|
listLabel |
Name of the user field in the list |
|
formLabel |
Name of the user field in the card |
|
filterLabel |
Name of the user field in the filter |
CRM Object Type
Different methods specify the CRM object type in one of four formats:
entityTypeId— for example, in thecrm.item.*methods, in activity bindings, and in SPA linksentityTypeName— for example, in theENTITY_TYPEfield of the crm.timeline.comment.* methods. The response returns the value in lowercase; case does not matter when writingentityTypeAbbr— in the values of fields bound to multiple types and inownerTypeof product itemsuserFieldEntityId— in user field methods
|
Object Type |
Numeric Identifier of the Type |
Symbolic Code of the Type |
Short Symbolic Code of the Type |
User Field Object Type |
|
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 |
|
CRM document |
36 |
SMART_DOCUMENT |
DO |
CRM_SMART_DOCUMENT |
|
B2E document |
39 |
SMART_B2E_DOC |
SBD |
CRM_SMART_B2E_DOC |
|
SPA |
|
|
|
|
For an SPA, id and entityTypeId are different values; see the Smart Process Identifiers section for details. The list of object types including SPAs is returned by the crm.enum.ownertype method. In REST 3.0, system object types are returned by the crm.dictionary.entitytype.list method; its response does not include SPAs — they are returned by crm.type.list.
For new integrations, use "Invoice (new)" with entityTypeId = 31 (SMART_INVOICE). The INVOICE type with entityTypeId = 5 is retained for compatibility with the old invoice functionality and is not recommended for new projects.
Bind To CRM Items User Field Value
The value format of a crm field depends on the API version and on the field settings. The settings are returned in the settings key of the field description: types with the value Y are allowed.
The field supports binding to leads, deals, contacts, companies, orders, estimates, new invoices, and SPAs. Old invoices I cannot be selected in it.
In REST 3.0
The field is passed by its UF_CRM_… name. The value depends on how many types the binding is allowed to:
- one type — the numeric identifier of the item, for example
107 - several types — an object with the
entityTypeIdandentityIdkeys, for example{"entityTypeId": 4, "entityId": 31}
A multiple field accepts and returns an array of such values: [107, 31] or [{"entityTypeId": 3, "entityId": 2571}, {"entityTypeId": 4, "entityId": 31}]. REST 3.0 does not accept prefixed strings such as C_2571.
In the Previous Version
The value format of a crm field depends on how many object types the binding is allowed to:
- The binding is allowed to one type — the value contains only the item identifier without a prefix. The response returns it as a string, for example
"107". - The binding is allowed to several types — the value has the
{PREFIX}_{ID}format, wherePREFIXis the short symbolic code of the typeentityTypeAbbrfrom the CRM Object Type table, andIDis the numeric identifier of the item. For an SPA withentityTypeId = 177→b1→PREFIXTb1.
Examples of prefixed values:
|
Object Type |
Example Value |
|
Lead |
|
|
Deal |
|
|
Contact |
|
|
Company |
|
|
Invoice (new) |
|
|
SPA |
|
If the field is multiple (isMultiple: true), the values are passed as an array of strings in the same format:
["C_123", "CO_456"]
or, if one type is allowed:
["107", "31"]
Address User Field Value
In REST 3.0
The value is passed and returned as an object with the address, latitude, and longitude keys:
{"address": "Tiergartenstraße 17, 10785 Berlin, Germany", "latitude": 52.51, "longitude": 13.37}
In the Previous Version
A user field of the address type stores the address as a single string of three parts separated by the | character:
{address}|{latitude};{longitude}|{address ID}
{address}— the address as text{latitude};{longitude}— coordinates separated by a semicolon. If there are no coordinates,;remains in their place{address ID}— identifier of the address in the Bitrix24 location module. May be missing if the value was written with coordinates
Example of a value in the response:
Tiergartenstraße 17, 10785 Berlin, Germany|52.5096;13.3700|453
When writing, pass a string in the {address}|{latitude};{longitude} format — it is retained as is, without an identifier. If you pass only the address text, Bitrix24 creates the address in the location module and adds empty coordinates and the identifier itself: {address}|;|{address ID}.
Requisite addresses work differently: they are stored in separate fields — street, city, postal code, and others. They are described in CRM Company Details Addresses.
Language Identifiers for Bitrix24
A language identifier is a string of two Latin letters. The set of languages depends on Bitrix24: localization keys contain the installed languages. The table lists the most common languages.
|
Language Identifier |
Language |
|
|
Arabic |
|
|
Portuguese (Brazil) |
|
|
German |
|
|
English |
|
|
French |
|
|
Hindi |
|
|
Indonesian |
|
|
Italian |
|
|
Japanese |
|
|
Kazakh |
|
|
Spanish |
|
|
Malay |
|
|
Polish |
|
|
Russian |
|
|
Chinese |
|
|
Chinese (Taiwan) |
|
|
Thai |
|
|
Turkish |
|
|
Ukrainian |
|
|
Uzbek |
|
|
Vietnamese |