Linking Deals to Contacts: Overview of Methods

The group of methods crm.deal.contact.* links contacts to a deal and removes that link. A deal can have several linked contacts, one of which is considered primary. The methods crm.deal.contact.* work with a single contact, and the methods crm.deal.contact.items.* work with the entire set of contacts at once.

Quick navigation: all methods

How the Link Is Structured in the APIHow the Link Is Structured in the API

The link is described by three fields, and their composition is returned by the method crm.deal.contact.fields.

Field	Type	Description
CONTACT_ID	integer	Identifier of the contact, a required field. You can retrieve it using the method crm.contact.list
IS_PRIMARY	char	Indicates the primary contact of the deal, Y or N. The first linked contact becomes the primary one, as does the contact for which Y is explicitly passed
SORT	integer	Order of the contact in the deal detail form

A deal has only one company. Its identifier is retained in the deal field COMPANY_ID and is changed using the method crm.deal.update. A separate group of methods is needed only for contacts, because a deal can have several of them.

How to Retrieve and Change the Set of ContactsHow to Retrieve and Change the Set of Contacts

The multiple field CONTACT_IDS is available in the methods crm.deal.add and crm.deal.update, but it is not returned by the methods crm.deal.get and crm.deal.list. To read the contacts of an existing deal, use the method crm.deal.contact.items.get.

The methods change the set of contacts in different ways, and this determines which one to choose:

• crm.deal.contact.add adds a single contact to those already linked. If the contact is already linked to the deal, the method returns false and changes nothing
• crm.deal.contact.items.set replaces the entire set: contacts that are not in the list you pass are unlinked from the deal
• crm.deal.contact.delete removes a single contact from the deal, and crm.deal.contact.items.delete removes all of them at once

The link can also be changed using the universal method crm.item.update with entityTypeId = 2 — there the field is named contactIds.

Benefits of Linking Deals to ContactsBenefits of Linking Deals to Contacts

• The deal detail form displays information about related contacts: name, phone number, e-mail, and position
• You can call a contact or send an e-mail directly from the deal detail form without navigating to the contact detail form
• E-mails, calls, and chats from open lines are retained in both the contact detail form and the deal detail form. Communications are not attached to closed deals
• CoPilot in CRM processes client calls from the deal detail form: it transcribes recordings, summarizes conversations, and fills in fields in the CRM detail form
• When generating documents from a template, symbolic codes automatically insert data from related contacts into the document

Overview of MethodsOverview of Methods

Scope: crm

Who can execute the method: depending on the method — changing the set of contacts requires the "modify" access permission for deals, and reading it requires the "read" permission

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