Deals in CRM: Overview of Methods

A deal is one of the key objects in CRM, where you can:

• manage the sales process of a product or service, including tracking stages and accepting online payments
• engage in dialogue with the client: calls, e-mails, chats in open channels
• view the history of interactions: activities, timeline records

Quick navigation: all methods and events

User documentation: deals in Bitrix24

Current API VersionCurrent API Version

A deal is one of the CRM object types, so it is managed by the universal methods crm.item.* with entityTypeId = 2. The crm.deal.* methods remain only to support existing integrations.

If You Need To	Open the Method
Create a deal	crm.item.add
Update a deal	crm.item.update
Retrieve a deal by its identifier	crm.item.get
Retrieve a list of deals by filter	crm.item.list
Delete a deal	crm.item.delete
Retrieve the description of deal fields	crm.item.fields
Manage the product items of a deal	crm.item.productrow.* with ownerType = D
Configure the deal card	crm.item.details.configuration.*

In the universal methods, field names are written in camelCase: TITLE becomes title, and ASSIGNED_BY_ID becomes assignedById. Some fields are named differently: the deal stage STAGE_ID arrives in the stageId field, the funnel CATEGORY_ID — in the categoryId field, and the multiple field CONTACT_IDS — in the contactIds field. The exact set of fields is returned by the method crm.item.fields with entityTypeId = 2.

Getting StartedGetting Started

The following sequence is intended for new development, based on the universal methods.

1. Retrieve the description of deal fields using the method crm.item.fields with entityTypeId = 2 — it returns both system and custom fields with their types
2. Find out the available funnels using the method crm.category.list with the parameter entityTypeId = 2, and their stages using the method crm.status.list with the filter ENTITY_ID = DEAL_STAGE for the default funnel or DEAL_STAGE_<funnel_id> for the rest
3. Create a deal using the method crm.item.add: pass entityTypeId = 2, the title title, the funnel categoryId, the stage stageId, the amount opportunity with the currency currencyId, and the client — the company companyId or the contacts contactIds
4. Add product items with the group of methods crm.item.productrow.* using ownerType = D
5. Move the deal through stages and between funnels using the method crm.item.update
6. Subscribe to the deal events to receive notifications about changes in your application

Connection of Deals with Other CRM ObjectsConnection of Deals with Other CRM Objects

Client. A field in the deal card that consists of the associated company and contacts. All activities related to calls, e-mails, and chats with the contact or company will be saved in the active deal card. There can be only one company in the field, and it is accessed directly through the deal field COMPANY_ID. Multiple contacts can be specified, and interaction with them is conducted through a separate group of methods crm.deal.contact.*.

Products. The product items of a deal are created, modified, and deleted by the group of methods crm.item.productrow.*. The deal is specified in them by the pair ownerType = D and ownerId with the deal identifier.

Payments. The payment documents for a deal are created, modified, and deleted by the group of methods crm.item.payment.*.

Sales Funnels and Deal StagesSales Funnels and Deal Stages

Sales funnels are managed by the group of methods crm.category.* with entityTypeId = 2.

Each funnel has its own set of stages, managed by the group of CRM reference methods — crm.status.*. The stages of different funnels are stored in different references: for the default funnel, ENTITY_ID equals DEAL_STAGE, and for the rest — DEAL_STAGE_<funnel_id>, for example DEAL_STAGE_5.

You can retrieve the history of a deal's movement through stages using the method crm.stagehistory.list.

How to Change a Deal's FunnelHow to Change a Deal's Funnel

The method crm.deal.update can only change the stage of a deal within the current funnel. If you pass a STAGE_ID that does not belong to the current funnel, nothing will change.

To move a deal to a stage in another funnel, use the method crm.item.update with the following parameters:

• entityTypeId — 2 for the deal
• id — the identifier of the deal you are moving
• categoryId — the identifier of the funnel to which you are moving the deal. This can be obtained using the method crm.category.list
• stageId — the identifier of the stage in the new funnel. This can be obtained using the method crm.status.list

Moving a deal triggers the event onCrmDealMoveToCategory, not onCrmDealUpdate. A request example and the response breakdown are available on the page of the method crm.item.update.

Deal CardDeal Card

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

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

• the right part, which contains the deal's 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 parameters of the deal card can be managed depending on the funnel through the group of methods crm.deal.details.configuration.*.

WidgetsWidgets

You can embed an application into the deal card and work with it without leaving the card.

There are two embedding scenarios:

• use special embedding locations, for example, create your own tab
• create a custom field into which the interface of your application is loaded

Recurring DealsRecurring Deals

Similar deals can be created automatically from a template with a defined period and number of repetitions. Templates are managed by the group of methods crm.deal.recurring.*. The tool is not available on every Bitrix24 plan; the details are on the recurring deals page.

Overview of Methods and EventsOverview of Methods and Events

Scope: crm

Who can execute the method: depending on the method — the deal methods check the access permissions for deals, while creating, modifying, and deleting custom fields is available only to a CRM administrator. Any user can subscribe to the events

MainMain

Recurring DealsRecurring Deals

Custom FieldsCustom Fields

Deal ContactsDeal Contacts

Method	Description
crm.deal.contact.add	Links a single contact to a deal
crm.deal.contact.delete	Removes a single contact from a deal
crm.deal.contact.items.get	Returns the set of contacts linked to a deal
crm.deal.contact.items.set	Replaces the set of deal contacts with the one you pass
crm.deal.contact.items.delete	Removes all contacts from a deal
crm.deal.contact.fields	Returns the description of the fields for the deal-contact link

Managing Deal CardsManaging Deal Cards

Method	Description
crm.deal.details.configuration.get	Returns the settings for the deal card
crm.deal.details.configuration.set	Sets the settings for the deal card
crm.deal.details.configuration.reset	Resets the settings for the deal card
crm.deal.details.configuration.forceCommonScopeForAll	Forcefully sets a common deal card for all users