Reference Guides in CRM: Overview of Methods

In the detail forms of CRM entities, there are two types of list fields:

• Custom fields — these can be created, modified, and deleted using the methods crm.xx.userfield.*. For example, to create a custom list field in deals, use crm.deal.userfield.add.

• System fields — these are pre-installed and cannot be created or deleted. In system list fields, only the values of the list can be modified. The list of values for system list fields is referred to as a reference guide in CRM.

Quick navigation: all methods

User documentation: Statuses and dropdowns in CRM

Getting StartedGetting Started

1. Retrieve the list of reference guide types using the crm.status.entity.types method — it returns ENTITY_ID codes, for example DEAL_STAGE or SOURCE
2. Review the current values of a reference guide using the crm.status.entity.items method or the crm.status.list method with a filter by ENTITY_ID
3. Add a new value using the crm.status.add method: pass ENTITY_ID, a unique STATUS_ID code, and a NAME to it
4. Change the name, color, or sorting of a value using the crm.status.update method, and delete an unnecessary one using the crm.status.delete method
5. Use STATUS_ID in the methods of CRM objects, for example in crm.deal.update

List of Reference GuidesList of Reference Guides

To modify a reference guide, specify the ENTITY_ID parameter in the methods of the group crm.status.*. If the value is incorrect, another reference guide will be modified.

Stages. A reference guide with stages of working with clients, which are displayed in the CRM kanban. Each CRM object has its own code for the stages reference guide:

• Deals — DEAL_STAGE for the main deal pipeline and DEAL_STAGE_xx for an additional one, where xx is the ID of the pipeline.
• Leads — STATUS
• Invoices — SMART_INVOICE_STAGE_xx, where xx is the ID value of the invoice pipeline.
• Quotes — QUOTE_STATUS
• Documents — SMART_DOCUMENT_STAGE_xx, where xx is the ID value of the document pipeline.
• Smart Processes — DYNAMIC_xx_STAGE_xx, where the first xx is the entityTypeId of the smart process, and the second xx is the ID of the pipeline.

To obtain the ID of a specific pipeline in Bitrix24, use the method crm.status.entity.types.

Sources. A reference guide with values for the system field Source — SOURCE.

Contact and Company Types. Reference guides with values for the system fields Contact Type — CONTACT_TYPE and Company Type — COMPANY_TYPE.

Number of Employees. A reference guide with values for the system field Number of Employees in the company detail form — EMPLOYEES.

Client Industry. A reference guide with values for the system field Industry in the company detail form — INDUSTRY.

Deal Type. A reference guide with values for the system field Deal Type in the deal detail form — DEAL_TYPE.

Honorifics. A reference guide with values for the system field Honorific in the lead and contact detail forms — HONORIFIC.

Call Statuses. A reference guide with values for the Call Status in the call list detail form — CALL_LIST.

How to Use Reference Guide ValuesHow to Use Reference Guide Values

Each list value in the reference guides has:

• name NAME — displayed in the CRM object detail form
• status STATUS_ID — used in methods for creating and modifying entities

Using the method crm.deal.update, you can change the values of the fields Deal Stage — STAGE_ID and Source — SOURCE_ID. Both fields are system list fields.

To display the name of the stage or source in the CRM detail form, it is important to pass the STATUS_ID of the value, not the NAME. For the stage "New Request," this might be C1:NEW, and for the source "call," it would be CALL.

Some reference guide values are system ones — their SYSTEM field contains Y. A system value cannot be created via REST: the crm.status.add method always saves a new element with SYSTEM = N. A system value can only be deleted with the FORCED flag in the crm.status.delete method.

Overview of MethodsOverview of Methods

Scope: crm

Who can execute the methods: depending on the method

Any user with access to CRM can read reference guides. Only an administrator or a user with the "Allow to modify settings" access permission in CRM can add, update, and delete reference guide elements.

Method	Description
crm.status.add	Creates a new element in the specified reference guide
crm.status.update	Updates an existing element of the reference guide
crm.status.get	Returns an element of the reference guide by its identifier
crm.status.list	Returns a list of elements from the reference guide based on a filter
crm.status.delete	Deletes an element from the reference guide
crm.status.entity.items	Returns elements of the reference guide by its symbolic identifier
crm.status.entity.types	Returns descriptions of reference guide types
crm.status.fields	Returns descriptions of reference guide fields