Add a Contact with Details via Web Form

Scope: crm

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

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

You can place a form on your website to collect client data and details. When a client fills out the form, their data will be sent to the CRM, and you will be able to process the request.

Setting up the form consists of two steps.

We will place the form on a PHP page. In the page code, we will retrieve the list of detail templates and address fields for the form. The form data will be sent to the handler.
We will create a file to process the data. The handler will accept and prepare the data, and then create a contact with the details.

1. Creating the Web Form

To generate the form fields, we will use data from Bitrix24. To obtain information about the detail settings, we will sequentially execute two methods:

crm.address.fields — we retrieve the list of address fields. The result is saved in arAddressFields.
```
$arAddressFields = CRest::call('crm.address.fields', []);
        
```

crm.requisite.preset.list — we request the list of detail templates. Using the select parameter, we choose the ID and NAME fields for each template. The result is saved in arRequisiteType.

$arRequisiteType = CRest::call(
            'crm.requisite.preset.list', [
                'select' => ["ID", "NAME"]
            ]
        );

We will add a web form to the website with the following fields:

REQ_TYPE — a dropdown list with the type of details from the arRequisiteType array, required,
NAME — contact's first name, required,
LAST_NAME — last name,
PHONE — phone number,
${addressFieldsInputs} — address fields, which are created dynamically from the arAddressFields array.

The form sends data using the POST method to the form.php file.

Complete Example of the Page with the Form

How to Use Examples in Documentation

<?php
        // Retrieve the list of address fields and detail templates
        $arAddressFields = CRest::call('crm.address.fields', []);
        $arRequisiteType = CRest::call('crm.requisite.preset.list', [
            'select' => ["ID", "NAME"]
        ]);
        
        if (!empty($arRequisiteType['result'])): 
            $arRequisiteType = array_column($arRequisiteType['result'], 'NAME', 'ID');
        
            // Remove system and unused address fields
            $excludeFields = ['TYPE_ID', 'ENTITY_TYPE_ID', 'ENTITY_ID', 'COUNTRY_CODE', 'ANCHOR_TYPE_ID', 'ANCHOR_ID'];
            foreach ($excludeFields as $field) {
                unset($arAddressFields['result'][$field]);
            }
        ?>
            <form id="form_to_crm">
                <select name="REQ_TYPE" required>
                    <option value="" disabled selected>Select a detail type</option>
                    <?php foreach ($arRequisiteType as $id => $name): ?>
                        <option value="<?=$id?>"><?=$name?></option>
                    <?php endforeach; ?>
                </select>
                <input type="text" name="NAME" placeholder="First Name" required>
                <input type="text" name="LAST_NAME" placeholder="Last Name">
                <input type="text" name="PHONE" placeholder="Phone">
                <?php foreach ($arAddressFields['result'] as $key => $arField): ?>
                    <input type="text" name="ADDRESS[<?=$key?>]" 
                           placeholder="<?=$arField['title']?>" 
                           <?=$arField['isRequired'] ? 'required' : ''?>>
                <?php endforeach; ?>
                <input type="submit" value="Submit">
            </form>
        <?php else: ?>
            <p>No available detail types.</p>
        <?php endif; ?>
        
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script> 
        <script>
        $(document).ready(function() {
            $('#form_to_crm').on('submit', function(el) {
                el.preventDefault();
                $.ajax({
                    method: 'POST',
                    dataType: 'json',
                    url: 'form.php',
                    data: $(this).serialize(),
                    success: function(data) {
                        alert(data.message);
                    }
                });
            });
        });
        </script>

2. Creating the Form Handler

To process the values from the form fields and add a contact to the CRM, we will create the handler form.php.

Preparing the Data

We retrieve and sanitize the data from the form:

REQ_TYPE is converted to an integer,
NAME, LAST_NAME, PHONE are sanitized from HTML tags.

$iRequisitePresetID = intVal($_POST["REQ_TYPE"]);
        $sName = htmlspecialchars($_POST["NAME"]);
        $sLastName = htmlspecialchars($_POST["LAST_NAME"]);
        $sPhone = htmlspecialchars($_POST["PHONE"]);

We prepare the address fields and collect them into the $arAddress array.

The values from the form fields are sanitized from HTML tags.
We add the address type TYPE_ID. The address types can be obtained using the method crm.enum.addresstype. We will specify the value — 1, which means the actual address.
We add the identifier for the object type ENTITY_TYPE_ID. The identifiers can be obtained using the method crm.enum.ownertype. We will specify the value — 8, which means detail.

$arAddress = [];
        foreach($_POST["ADDRESS"] as $key => $val) {
            $arAddress[$key] = htmlspecialchars($val);
        }
        $arAddress['TYPE_ID'] = 1;
        $arAddress['ENTITY_TYPE_ID'] = 8;

The system stores the phone as an array of objects crm_multifield, so it needs to be formatted as an array.

We add the phone as the first element VALUE in the array, and the second value specifies the type VALUE_TYPE, for example, WORK.
For an empty value, we pass an empty array.

$arPhone = !empty($sPhone) ? [['VALUE' => $sPhone, 'VALUE_TYPE' => 'WORK']] : [];

Adding the Contact

To create a contact, we will execute the method crm.contact.add. In the fields object, we pass the fields:

NAME — contact's first name,
LAST_NAME — last name,
PHONE — phone number.

Check which required fields are configured for contacts in your Bitrix24. All required fields must be passed to the method crm.contact.add.

CRest::call(
            'crm.contact.add', [
                'fields' => [
                    'NAME' => $sName,
                    'LAST_NAME' => $sLastName,
                    'PHONE' => $arPhone
                ]
            ]
        );

As a result, we will receive the identifier of the new contact, for example, 23.

{
        	"result": 23
        }

Adding Details to the Contact

To add details to the contact, we will execute the method crm.requisite.add. In the fields object, we pass the fields:

ENTITY_TYPE_ID — identifier of the object type. The identifiers can be obtained using the method crm.enum.ownertype. In this example, we will specify the value 3, which means contact,
ENTITY_ID — identifier of the contact received in the previous request,
PRESET_ID — identifier of the detail template received from the form,
ACTIVE — activity of the detail Y,
NAME — name of the detail, for example, we will combine the first name and last name of the contact.

CRest::call(
            'crm.requisite.add', 
            [
                'fields' => [
                    'ENTITY_TYPE_ID' => 3,
                    'ENTITY_ID' => $contactId,
                    'PRESET_ID' => $iRequisitePresetID,
                    'ACTIVE' => 'Y',
                    'NAME' => implode(' ', [$sName, $sLastName]),
                ]
            ]
        );

As a result, we will receive the identifier of the details.

{
            "result": 34
        }

Adding an Address for the Detail

We will add an address for the detail using the method crm.address.add, if the detail was created successfully. In $arAddress, we add ENTITY_ID with the ID of the detail from the response of the previous request. In the fields object, we pass the $arAddress array with the address fields.

if(!empty($resultRequisite['result'])) {
        	$arAddress['ENTITY_ID'] = $resultRequisite['result'];
        	CRest::call(
        		'crm.address.add',
        		[
        			'fields' => $arAddress
        		]
        	);
        }

Complete Example of the Handler Code

<?php
        require_once('crest.php');
        
        // Retrieve and sanitize form data
        $iRequisitePresetID = intVal($_POST["REQ_TYPE"]);
        $sName = htmlspecialchars($_POST["NAME"]);
        $sLastName = htmlspecialchars($_POST["LAST_NAME"]);
        $sPhone = htmlspecialchars($_POST["PHONE"]);
        
        // Prepare address
        $arAddress = [];
        foreach ($_POST["ADDRESS"] as $key => $val) {
            $arAddress[$key] = htmlspecialchars($val);
        }
        $arAddress['TYPE_ID'] = 1; // Actual address
        $arAddress['ENTITY_TYPE_ID'] = 8; // Object type — detail
        
        // Format phone for Bitrix24
        $arPhone = !empty($sPhone) ? [['VALUE' => $sPhone, 'VALUE_TYPE' => 'WORK']] : [];
        
        // Create contact
        $result = CRest::call('crm.contact.add', [
            'fields' => [
                'NAME' => $sName,
                'LAST_NAME' => $sLastName,
                'PHONE' => $arPhone
            ]
        ]);
        
        // Retrieve the identifier of the new contact
        if (!empty($result['result'])) {
            $contactId = $result['result'];
        
            // Add details for the new contact
            $resultRequisite = CRest::call('crm.requisite.add', [
                'fields' => [
                    'ENTITY_TYPE_ID' => 3, // Object type — contact
                    'ENTITY_ID' => $contactId,
                    'PRESET_ID' => $iRequisitePresetID,
                    'ACTIVE' => 'Y',
                    'NAME' => implode(' ', [$sName, $sLastName]),
                ]
            ]);
        
            // Add address if details were created successfully
            if (!empty($resultRequisite['result'])) {
                $arAddress['ENTITY_ID'] = $resultRequisite['result'];
                CRest::call('crm.address.add', ['fields' => $arAddress]);
            }
        
            echo json_encode(['message' => 'Contact successfully added']);
        } else {
            $error = !empty($result['error_description']) ? $result['error_description'] : 'Unknown error';
            echo json_encode(['message' => 'Error: ' . $error]);
        }
        ?>

Add Contact

Add Company

Add a Contact with Details via Web Form

1. Creating the Web Form1. Creating the Web Form

Complete Example of the Page with the FormComplete Example of the Page with the Form

2. Creating the Form Handler2. Creating the Form Handler

Preparing the DataPreparing the Data

Adding the ContactAdding the Contact

Adding Details to the ContactAdding Details to the Contact

Adding an Address for the DetailAdding an Address for the Detail

Complete Example of the Handler CodeComplete Example of the Handler Code