Migrating to the New CRM Methods

This page helps you migrate an integration from the CRM methods of the previous API version to REST 3.0: find the equivalent of each method, take into account what REST 3.0 does not support yet, and update the request and response format.

Migration StepsMigration Steps

1. Find the equivalents of the methods your integration uses by following the rules in the How to Find the Equivalent of a Method section. If REST 3.0 does not support a task, keep that call in the previous version: such tasks are listed in the What REST 3.0 Does Not Support Yet section
2. Change the call address from /rest/ to /rest/api/. The method name stays the same for deals, leads, contacts, companies, and estimates. For SPAs and invoices, it changes to crm.<type>.<action>, for example crm.smartprocess1038.add
3. Rename the fields to camelCase: TITLE → title, STAGE_ID → stageId. The field names of each type are listed on the fields pages, for example Deal fields
4. List the fields you need in the select parameter. Without it, the get and list methods return only id
5. Update the handling of responses and errors: data comes in the result object, and errors come in the error object with a code and a message. The format is described in the REST 3.0 overview
6. Test the new calls on test data before switching over the production scenario

Example: Creating a DealExample: Creating a Deal

In the previous version, fields are passed in uppercase, and the method returns the ID as a number.

curl -X POST \
        -H "Content-Type: application/json" \
        -d '{"FIELDS":{"TITLE":"Purchase request","ASSIGNED_BY_ID":1,"OPPORTUNITY":150000,"CURRENCY_ID":"EUR"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.add
        

{
            "result": 9021
        }
        

In REST 3.0, the same call goes to the /rest/api/ address, fields are passed in camelCase, and the ID comes in the result object.

curl -X POST \
        -H "Content-Type: application/json" \
        -d '{"fields":{"title":"Purchase request","assignedById":1,"opportunity":150000,"currencyId":"EUR"}}' \
        https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.add
        

{
            "result": {
                "id": 9023
            }
        }
        

How to Find the Equivalent of a MethodHow to Find the Equivalent of a Method

Methods of deals, leads, contacts, companies, and estimates. The method name in REST 3.0 is the same, and only the call address changes. For example, crm.deal.add, crm.deal.get, crm.deal.list, crm.deal.update, and crm.deal.delete exist in both versions, as do the add, get, list, update, and delete methods of leads, contacts, companies, and estimates.

Universal methods crm.item.*. In REST 3.0, the object type is part of the method name, so the entityTypeId parameter is not needed. For example, crm.item.add with entityTypeId: 2 becomes the crm.deal.add method, and crm.item.list with entityTypeId: 1038 becomes the crm.smartprocess1038.list method. Product items of an item also get the type in the name: for a deal, crm.item.productrow.add becomes crm.deal.productrow.add. The segments of all types are listed in the CRM overview.

Other methods have different names in REST 3.0. They are listed in the table. The table uses deal methods as examples, and company methods for requisites and addresses. For other object types, the name contains their segment instead of deal or company: crm.lead.field.list, crm.contact.requisite.add.

What REST 3.0 Does Not Support YetWhat REST 3.0 Does Not Support Yet

For these tasks, keep the calls of the previous version at the /rest/ address.

How REST 3.0 Differs from the Previous VersionHow REST 3.0 Differs from the Previous Version

• One scheme for all types. The crm.<type>.* methods work the same way for deals, leads, contacts, companies, estimates, invoices, and SPAs. Only the set of groups and the fields of the type differ
• Field names in camelCase. The deal stage is the stageId field, not STAGE_ID. Custom fields keep names like UF_CRM_…
• Fields are selected explicitly. Without select, the crm.<type>.get and crm.<type>.list methods return only the item id. In select, you can request fields of linked objects with dot notation, for example assignedBy.lastName or stage.name. Nested groups have their own select rules, which are described on the method pages
• New filter and pagination format. The filter, order, and pagination parameters follow the general REST 3.0 rules. The crm.<type>.list method returns 50 items by default, up to 1000. In list methods of nested groups, the filter usually requires a condition on the owner, for example ownerId, and the page limit may be lower
• Field descriptions in every group. Each group of methods has its own field.get and field.list, for example crm.deal.productrow.field.list returns the fields of a product item

The parameter and response format is described in the REST 3.0 overview: selecting fields and linked objects, filtering, comparison with the old version.