Leads in CRM: Overview of Methods

A lead is the starting point of the Sales Funnel. Its card contains information about the client's interest in a product or service: filled CRM forms, e-mails, calls, and chats with the client.

The main goal of working with leads is to determine their potential and convert them into deals for further selling of the product or service.

Quick navigation: all methods and events

User documentation: leads in Bitrix24

Current API VersionCurrent API Version

Development of the crm.lead.* and crm.lead.details.configuration.* methods has been discontinued. For new development, use the universal methods crm.item.* and pass entityTypeId: 1 to them — this is the identifier of the "Lead" object type. The crm.lead.* methods continue to work — retain them only in existing integrations.

Method with Discontinued Development	Replacement
crm.lead.add	crm.item.add
crm.lead.update	crm.item.update
crm.lead.get	crm.item.get
crm.lead.list	crm.item.list
crm.lead.delete	crm.item.delete
crm.lead.fields	crm.item.fields
crm.lead.productrows.*	crm.item.productrow.*
crm.lead.details.configuration.*	crm.item.details.configuration.*

The crm.lead.contact.* and crm.lead.userfield.* method groups have no replacement — they are current.

Field names differ between the two method groups: crm.lead.* accepts and returns fields in UPPER_CASE format, for example STATUS_ID, while crm.item.* uses camelCase format, for example statusId.

How to Get StartedHow to Get Started

1. Retrieve the list of lead fields with the crm.lead.fields method. It returns system and custom fields with their types and names.
2. Create a lead with the crm.lead.add method. A lead has no required fields, but without a filled TITLE it will be hard to find in the list.
3. Add product items to the lead with the crm.lead.productrows.set method if the client's request concerns specific products.
4. Link the lead to contacts with the crm.lead.contact.* methods if the client is already in the database.
5. Move the lead through the stages with the crm.lead.update method by changing the STATUS_ID field. The list of stages is returned by the crm.status.list method with the filter[ENTITY_ID]=STATUS filter.
6. Subscribe to lead events to receive notifications about changes in real time.

Connection of Leads with Other CRM ObjectsConnection of Leads with Other CRM Objects

Products. The product items of a lead are set by the crm.lead.productrows.set method and returned by crm.lead.productrows.get. The universal replacement for these methods is the crm.item.productrow.* group with the ownerType: L parameter.

Deal. The connection appears after converting the lead into a successful one.

Client. A field in the lead card consisting of the associated company and contacts. The field is available in the repeat lead form. If repeat leads are disabled, the linking field appears after creating a company or contact based on the lead. There is one company in the lead, and access to it is made directly through the field COMPANY_ID. Multiple contacts can be specified, and interaction with them is conducted through a separate group of methods crm.lead.contact.*.

Lead CardLead Card

The main workspace in a lead is the General tab of its card. It consists of two parts:

• The left part contains fields with information. If the system fields are insufficient, you can create your own custom fields. They allow storing information in various data formats: string, number, link, address, and others. To create, modify, retrieve, or delete custom lead fields, the group of methods crm.lead.userfield.* is used.

• The right part contains the lead timeline. In it, you can create, edit, filter, and delete CRM activities — the group of methods crm.activity.*, and timeline records — the group of methods crm.timeline.*.

The composition of sections and fields of the lead card is managed by the group of methods crm.lead.details.configuration.*. Configurations are set separately for the simple lead card and the repeat lead card.

WidgetsWidgets

An application can be embedded into the lead card. Thanks to embedding, you can use the application without leaving the lead card.

There are two embedding scenarios:

• Use special embedding locations. For example, by creating your own tab.
• Create a custom field, into which the content of your application will be loaded.

FeaturesFeatures

A lead may not be retained as a lead. Bitrix24 has two CRM operating modes. In classic mode, a lead remains in the system after creation. In simple mode there are no leads: the system immediately converts a created lead into a deal, and it can no longer be retrieved with the crm.lead.get method. Check the mode with the crm.settings.mode.get method before building a scenario around leads.

Conversion is not available in REST. There is no separate method for converting a lead into a contact, company, or deal. Through the API, you can only move the lead to a successful stage with the crm.lead.update method — no new objects are created, and they have to be created with separate calls to crm.contact.add, crm.company.add, and crm.deal.add.

A repeat lead is determined by the system. The repeat lead indicator IS_RETURN_CUSTOMER is read-only: it is set to Y automatically when the lead has the CONTACT_ID or COMPANY_ID field filled. IS_RETURN_CUSTOMER cannot be passed directly to crm.lead.add or crm.lead.update — the value is recalculated.

Overview of Methods and EventsOverview of Methods and Events

Scope: crm

Who can execute the method: depending on the method

MainMain

Connection Between Leads and ContactsConnection Between Leads and Contacts

Method	Description
crm.lead.contact.add	Adds a contact binding to the specified lead
crm.lead.contact.delete	Removes a contact binding from the specified lead
crm.lead.contact.items.get	Retrieves a list of contacts associated with the lead
crm.lead.contact.items.set	Attaches a list of contacts to the specified lead
crm.lead.contact.items.delete	Removes the list of contacts from the lead
crm.lead.contact.fields	Retrieves the description of fields for lead-contact connection, used by methods of the crm.lead.contact.* family

Custom FieldsCustom Fields

Managing Lead CardsManaging Lead Cards

Method	Description
crm.lead.details.configuration.set	Sets the settings for lead cards
crm.lead.details.configuration.get	Retrieves the settings parameters for lead cards
crm.lead.details.configuration.reset	Resets the settings for lead cards
crm.lead.details.configuration.forceCommonScopeForAll	Forces a common lead card for all users