How to Create a Vendor in CRM

Scope: crm

Who can execute the method: users with permission to create contacts or companies in CRM

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect the MCP server so that the assistant can utilize the official REST documentation.

Vendors are CRM contacts and companies marked with a system category:

CATALOG_CONTRACTOR_CONTACT — for contacts,
CATALOG_CONTRACTOR_COMPANY — for companies.

To create a vendor, we will sequentially execute two methods:

crm.category.list — retrieve the category ID for the contact or company.
crm.item.add — create a contact or company as a vendor.

1. Retrieve the Vendor Category ID

We will use the method crm.category.list with the following parameters:

entityTypeId — the ID of the CRM object type. Specify 3 for contacts. Use 4 for companies.
filter[code] — filter by category code. Specify CATALOG_CONTRACTOR_CONTACT for contacts. Use CATALOG_CONTRACTOR_COMPANY for companies.

How to Use Examples in Documentation

PHP

Python

BX24.callMethod(
            'crm.category.list',
            {
                entityTypeId: 3, 
                filter: {
                    code: 'CATALOG_CONTRACTOR_CONTACT'
                }
            },
            function(result) {
                console.log(result.data());
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'crm.category.list',
            [
                'entityTypeId' => 3,
                'filter' => [
                    'code' => 'CATALOG_CONTRACTOR_CONTACT'
                ]
            ]
        );

from b24pysdk import BitrixWebhook, Client
        
        
        client = Client(BitrixWebhook(domain="your-domain.bitrix24.com", auth_token="your-webhook"))
        
        response = client.crm.category.list(
            entity_type_id=3,
            filter={
                "code": "CATALOG_CONTRACTOR_CONTACT",
            },
        ).response
        
        print(response.result)

As a result, we will obtain the category ID. In the example, id is 15. The ID may vary across different Bitrix24 instances.

{
          "result": {
            "categories": [
              {
                "id": 15,
                "name": "Vendor Contacts",
                "entityTypeId": 3,
                "isSystem": "Y",
                "code": "CATALOG_CONTRACTOR_CONTACT"
              }
            ]
          }
        }

2. Create the Vendor

We will use the method crm.item.add with the following parameters:

entityTypeId — the ID of the CRM object type. Specify 3 for contacts. Use 4 for companies.
fields[categoryId] — the ID of the system category from step 1. In the example, it is 15.
fields[name] — first name.
fields[lastName] — last name. For companies, instead of first and last names, you can provide the fields[title] field — the company name.
fields[fm] — an array of multi-fields crm_multifield for phone and email.
fields[comments] — comments.

The system stores phone and email as an array of multi-fields fm. Each element of the array contains:

typeId — the type of multi-field, PHONE or EMAIL,
valueType — the type of value, such as WORK or MOBILE,
value — the field value.

PHP

Python

BX24.callMethod(
            'crm.item.add',
            {
                entityTypeId: 3, 
                fields: {
                    name: 'John',
                    lastName: 'Doe',
                    categoryId: 15,  // id from step 1
                    fm: [
                        { typeId: 'PHONE', valueType: 'WORK', value: '+1 900 000 00 00' },
                        { typeId: 'PHONE', valueType: 'MOBILE', value: '+1 495 111 22 33' },
                        { typeId: 'EMAIL', valueType: 'WORK', value: 'supplier@example.com' }
                    ],
                    comments: 'Electronics Supplier'
                }
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error() + ': ' + result.error_description());
                } else {
                    console.log(result.data());
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'crm.item.add',
            [
                'entityTypeId' => 3,
                'fields' => [
                    'name' => 'John',
                    'lastName' => 'Doe',
                    'categoryId' => 15, // id from step 1
                    'fm' => [
                        [ 'typeId' => 'PHONE', 'valueType' => 'WORK', 'value' => '+1 900 000 00 00' ],
                        [ 'typeId' => 'PHONE', 'valueType' => 'MOBILE', 'value' => '+1 495 111 22 33' ],
                        [ 'typeId' => 'EMAIL', 'valueType' => 'WORK', 'value' => 'supplier@example.com' ]
                    ],
                    'comments' => 'Electronics Supplier'
                ]
            ]
        );

response = client.crm.item.add(
            entity_type_id=3,
            fields={
                "name": "John",
                "lastName": "Doe",
                "categoryId": 15,
                "fm": [
                    {"typeId": "PHONE", "valueType": "WORK", "value": "+1 900 000 00 00"},
                    {"typeId": "PHONE", "valueType": "MOBILE", "value": "+1 495 111 22 33"},
                    {"typeId": "EMAIL", "valueType": "WORK", "value": "supplier@example.com"},
                ],
                "comments": "Electronics Supplier",
            },
        ).response
        
        print(response.result)

As a result, the method will return an item object with the data of the created vendor.

{
            "result": {
                "item": {
                    "id": 2449,
                    "createdTime": "2025-12-29T13:18:40+01:00",
                    "updatedTime": "2025-12-29T13:18:40+01:00",
                    "createdBy": 1,
                    "updatedBy": 1,
                    "assignedById": 1,
                    "opened": "Y",
                    "companyId": null,
                    "name": "John",
                    "lastName": "Doe",
                    "secondName": null,
                    "shortName": null,
                    "photo": null,
                    "post": null,
                    "address": null,
                    "comments": "Electronics Supplier",
                    "leadId": null,
                    "export": "Y",
                    "webformId": null,
                    "originatorId": null,
                    "originId": null,
                    "originVersion": null,
                    "birthdate": null,
                    "honorific": null,
                    "hasPhone": "Y",
                    "hasEmail": "Y",
                    "hasImol": "N",
                    "searchContent": null,
                    "categoryId": 15,
                    "lastActivityBy": 1,
                    "lastActivityTime": "2025-12-29T13:18:40+01:00",
                    "login": null,
                    "emailHome": null,
                    "emailWork": null,
                    "emailMailing": null,
                    "phoneMobile": null,
                    "phoneWork": null,
                    "phoneMailing": null,
                    "imol": null,
                    "email": null,
                    "phone": null,
                    "lastCommunicationTime": null,
                    "lastCommunicationCallTime": null,
                    "lastCommunicationEmailTime": null,
                    "lastCommunicationImolTime": null,
                    "lastCommunicationWebformTime": null,
                    "observers": [],
                    "companyIds": [],
                    "entityTypeId": 3,
                    "fm": [
                        {
                            "id": 8297,
                            "valueType": "WORK",
                            "value": "+1 900 000 00 00",
                            "typeId": "PHONE"
                        },
                        {
                            "id": 8299,
                            "valueType": "MOBILE",
                            "value": "+1 495 111 22 33",
                            "typeId": "PHONE"
                        },
                        {
                            "id": 8301,
                            "valueType": "WORK",
                            "value": "supplier@example.com",
                            "typeId": "EMAIL"
                        }
                    ]
                }
            },
            "time": {
                "start": 1767003520,
                "finish": 1767003520.776535,
                "duration": 0.7765350341796875,
                "processing": 0,
                "date_start": "2025-12-29T13:18:40+01:00",
                "date_finish": "2025-12-29T13:18:40+01:00",
                "operating_reset_at": 1767004120,
                "operating": 0.4402291774749756
            }
        }

The vendor ID, in this example id: 2449, should be used in the inventory accounting method catalog.documentcontractor.add.

Code Example

PHP

Python

var entityTypeId = 3; // 3 - contact; for company use 4
        var categoryCode = 'CATALOG_CONTRACTOR_CONTACT'; // for company use CATALOG_CONTRACTOR_COMPANY
        var categoryId = null;
        
        BX24.callMethod(
            'crm.category.list',
            {
                entityTypeId: entityTypeId,
                filter: { code: categoryCode }
            },
            function(resultCategory) {
                if (resultCategory.error()) {
                    console.error(resultCategory.error() + ': ' + resultCategory.error_description());
                    return;
                }
        
                var categories = resultCategory.data().categories || [];
                if (!categories.length) {
                    console.error('Vendor category not found');
                    return;
                }
        
                categoryId = categories[0].id;
        
                BX24.callMethod(
                    'crm.item.add',
                    {
                        entityTypeId: entityTypeId,
                        fields: {
                            name: 'John',
                            lastName: 'Doe',
                            categoryId: categoryId,
                            fm: [
                                { typeId: 'PHONE', valueType: 'WORK', value: '+1 900 000 00 00' },
                                { typeId: 'PHONE', valueType: 'MOBILE', value: '+1 495 111 22 33' },
                                { typeId: 'EMAIL', valueType: 'WORK', value: 'supplier@example.com' }
                            ],
                            comments: 'Electronics Supplier'
                        }
                    },
                    function(resultItem) {
                        if (resultItem.error()) {
                            console.error(resultItem.error() + ': ' + resultItem.error_description());
                        } else {
                            console.log(resultItem.data());
                        }
                    }
                );
            }
        );

require_once('crest.php');
        
        $entityTypeId = 3; // 3 - contact; for company use 4
        $categoryCode = 'CATALOG_CONTRACTOR_CONTACT'; // for company use CATALOG_CONTRACTOR_COMPANY
        
        $resultCategory = CRest::call(
            'crm.category.list',
            [
                'entityTypeId' => $entityTypeId,
                'filter' => [
                    'code' => $categoryCode
                ]
            ]
        );
        
        if (!empty($resultCategory['error_description'])) {
            echo $resultCategory['error_description'];
            return;
        }
        
        $categories = $resultCategory['result']['categories'] ?? [];
        if (empty($categories)) {
            echo 'Vendor category not found';
            return;
        }
        
        $categoryId = $categories[0]['id'];
        
        $resultItem = CRest::call(
            'crm.item.add',
            [
                'entityTypeId' => $entityTypeId,
                'fields' => [
                    'name' => 'John',
                    'lastName' => 'Doe',
                    'categoryId' => $categoryId,
                    'fm' => [
                        [ 'typeId' => 'PHONE', 'valueType' => 'WORK', 'value' => '+1 900 000 00 00' ],
                        [ 'typeId' => 'PHONE', 'valueType' => 'MOBILE', 'value' => '+1 495 111 22 33' ],
                        [ 'typeId' => 'EMAIL', 'valueType' => 'WORK', 'value' => 'supplier@example.com' ]
                    ],
                    'comments' => 'Electronics Supplier'
                ]
            ]
        );
        
        if (!empty($resultItem['error_description'])) {
            echo $resultItem['error_description'];
        } else {
            print_r($resultItem['result']);
        }

from b24pysdk import BitrixWebhook, Client
        from b24pysdk.errors import BitrixAPIError
        
        
        client = Client(BitrixWebhook(domain="your-domain.bitrix24.com", auth_token="your-webhook"))
        
        entity_type_id = 3  # 3 - contact; for company use 4
        category_code = "CATALOG_CONTRACTOR_CONTACT"  # for company use CATALOG_CONTRACTOR_COMPANY
        
        try:
            category_response = client.crm.category.list(
                entity_type_id=entity_type_id,
                filter={
                    "code": category_code,
                },
            ).response
        except BitrixAPIError as error:
            print(error)
        else:
            categories = category_response.result.get("categories") or []
            if not categories:
                print("Vendor category not found")
            else:
                category_id = categories[0]["id"]
        
                try:
                    item_response = client.crm.item.add(
                        entity_type_id=entity_type_id,
                        fields={
                            "name": "John",
                            "lastName": "Doe",
                            "categoryId": category_id,
                            "fm": [
                                {"typeId": "PHONE", "valueType": "WORK", "value": "+1 900 000 00 00"},
                                {"typeId": "PHONE", "valueType": "MOBILE", "value": "+1 495 111 22 33"},
                                {"typeId": "EMAIL", "valueType": "WORK", "value": "supplier@example.com"},
                            ],
                            "comments": "Electronics Supplier",
                        },
                    ).response
                except BitrixAPIError as error:
                    print(error)
                else:
                    print(item_response.result)

Add Company with Requisites

Add Deal and Company with Requisites

How to Create a Vendor in CRM

1. Retrieve the Vendor Category ID1. Retrieve the Vendor Category ID

2. Create the Vendor2. Create the Vendor

Code ExampleCode Example

1. Retrieve the Vendor Category ID

2. Create the Vendor

Code Example