How to Update Multiple Fields in Bitrix24 CRM Lead Using REST API

Updating multiple fields in Bitrix24 CRM leads using the REST API requires understanding the proper field formatting and API structure. When setting a lead status to ‘LOST’ while simultaneously updating enumeration fields like competitor products and URL fields, you must ensure proper value formats and handle required fields correctly. The Bitrix24 REST API uses specific data structures for different field types that must be followed precisely to avoid errors.

Contents

• Understanding Bitrix24 REST API for Lead Updates
• Correct Format for Updating Multiple Fields in Bitrix24 CRM Leads
• Handling Different Field Types (Status, Enumeration, URL)
• Common Issues and Solutions for Required Fields
• Code Examples for Bitrix24 Lead API Updates
• Sources
• Conclusion

Understanding Bitrix24 REST API for Lead Updates

The Bitrix24 REST API provides a comprehensive interface for managing CRM entities, including leads. When working with lead updates, it’s essential to understand the API’s structure and requirements. The API uses HTTP methods (primarily POST and PUT) to perform operations, with specific endpoints dedicated to CRM lead management.

For updating multiple fields in a lead simultaneously, you’ll typically use the crm.lead.update method. This method accepts an array of fields and values to be updated. The key challenge lies in understanding how different field types are represented in the API calls, especially when dealing with status changes, enumeration fields, and URL fields in the same request.

The Bitrix24 CRM system uses different data structures for various field types, which must be correctly formatted in your API calls. When updating a lead to set its status to ‘LOST’, you’re not just changing a simple value but potentially triggering business logic that might affect other fields or processes in the CRM system.

According to the Bitrix24 API documentation, the CRM tutorials section provides detailed guidance on working with different field types and implementing complex updates. Understanding these concepts is crucial for successfully updating multiple fields simultaneously while maintaining data integrity.

Correct Format for Updating Multiple Fields in Bitrix24 CRM Leads

To properly update multiple fields in a Bitrix24 CRM lead using the REST API, you need to structure your request correctly. The standard format for updating multiple fields involves sending a POST request to the appropriate API endpoint with a properly formatted JSON payload.

For the crm.lead.update method, the request should include:

• The lead ID (required)
• An array of fields to update in the fields parameter
• Properly formatted values for each field type

Here’s the basic structure:

<?php
$arParams = [
 'id' => $leadId,
 'fields' => [
 'STATUS_ID' => 'LOST',
 'COMPETITOR_PRODUCT' => $competitorId, // For enumeration fields
 'COMPETITOR_URL' => 'https://example.com', // For URL fields
 // Other fields as needed
 ]
];
?>

The critical aspect is understanding how Bitrix24 represents different data types in the API:

• Simple text fields: Direct string values
• Enumeration fields: Their numeric IDs, not display values
• Status fields: Status ID values (like ‘LOST’)
• URL fields: Full URL strings
• Date fields: Properly formatted date strings

When updating multiple fields simultaneously, ensure all required fields are either provided in the request or have default values in the CRM system. Missing required fields will cause the update to fail, as noted in the Bitrix24 CRM tutorials.

The API also supports selective field updates, meaning you only need to include the fields you want to change in the request, which helps maintain existing field values that you don’t intend to modify.

Handling Different Field Types (Status, Enumeration, URL)

Bitrix24 CRM handles different field types in specific ways when updating leads via the REST API. Understanding these differences is crucial for successful field updates, especially when working with status changes, enumeration fields, and URL fields simultaneously.

Status Fields

When updating a lead status to ‘LOST’, you need to use the status ID rather than the status name. Status IDs are typically uppercase strings like ‘LOST’, ‘NEW’, ‘IN_PROCESS’, etc. To find the correct status ID for your Bitrix24 installation:

1. Navigate to CRM settings
2. Find the lead status configuration
3. Identify the numeric or alphanumeric ID for the ‘LOST’ status

// Example of updating lead status
$fields = [
 'STATUS_ID' => 'LOST' // Not 'Lost' or 'lost'
];

Enumeration Fields

Enumeration fields (like competitor product) require special handling. These fields store predefined options and must be updated using their numeric IDs, not display names. To work with enumeration fields:

1. First retrieve the list of available options to find the correct ID
2. Use that ID in your update request

// Example of updating an enumeration field
$fields = [
 'COMPETITOR_PRODUCT' => 45 // Numeric ID, not the name
];

URL Fields

URL fields are simpler to handle as they typically store full URL strings. However, ensure the URLs are properly formatted and complete:

// Example of updating a URL field
$fields = [
 'COMPETITOR_URL' => 'https://www.example.com/products'
];

When updating multiple field types simultaneously, ensure each field is properly formatted according to its type. The Bitrix24 REST API will reject requests with incorrect field formats, as detailed in the official API documentation.

Common Issues and Solutions for Required Fields

When updating multiple fields in Bitrix24 CRM leads using the REST API, you’re likely to encounter several common issues, particularly related to required fields. Understanding these issues and their solutions can save significant development time and frustration.

Missing Required Fields

The most common issue is encountering “required field” errors when trying to update a lead. Bitrix24 CRM requires certain fields to have values before a lead can be saved or updated. When you attempt to update multiple fields, especially setting status to ‘LOST’, you might be missing one or more required fields.

Solution: Before updating, retrieve the current lead details to identify all required fields:

<?php
// Get current lead details first
$currentLead = $CrmRest->call('crm.lead.get', [
 'id' => $leadId,
 'select' => ['*', 'UF_*'] // Get all fields and custom fields
]);

// Check which fields are required
$requiredFields = $CrmRest->call('crm.lead.fields')['FIELDS'];
$fieldsToUpdate = [
 'STATUS_ID' => 'LOST',
 'COMPETITOR_PRODUCT' => $competitorId,
 'COMPETITOR_URL' => 'https://example.com'
];

// Ensure all required fields have values
foreach ($requiredFields as $field) {
 if ($field['IS_REQUIRED'] && !isset($fieldsToUpdate[$field['ID']])) {
 // Provide default values for required fields if needed
 $fieldsToUpdate[$field['ID']] = ''; // Or appropriate default
 }
}
?>

Field Type Mismatch

Another common issue is providing values in the wrong format for specific field types. For example, trying to pass a display name instead of an ID for enumeration fields.

Solution: Always use the correct data format for each field type:

• Status fields: Use status ID (e.g., ‘LOST’)
• Enumeration fields: Use numeric ID
• URL fields: Use complete URL string
• Date fields: Use properly formatted date string

Permission Issues

Sometimes, the API call fails due to insufficient permissions to update certain fields.

Solution: Ensure your API application has the necessary permissions to update the specific fields you’re modifying. This may require adjusting API scope settings or user permissions in Bitrix24.

Validation Errors

Bitrix24 performs validation on field values, and certain values might be rejected based on business rules.

Solution: Check the response for validation error messages and adjust your field values accordingly. The API response typically includes detailed error information to help pinpoint the issue.

Code Examples for Bitrix24 Lead API Updates

Practical code examples provide the clearest guidance for implementing multiple field updates in Bitrix24 CRM leads. Below are several examples demonstrating how to update different field types simultaneously, including setting the lead status to ‘LOST’ while updating enumeration and URL fields.

PHP Example: Complete Lead Update

<?php
// Bitrix24 REST API client initialization
$CrmRest = new \Bitrix24\Rest($domain, $applicationId, $applicationSecret, $accessToken);

$leadId = 123; // The ID of the lead to update
$competitorId = 45; // The numeric ID of the competitor product

$fields = [
 // Status field
 'STATUS_ID' => 'LOST',
 
 // Enumeration field (competitor product)
 'UF_CRM_1234567890' => $competitorId, // Replace with your actual custom field ID
 
 // URL field
 'UF_CRM_0987654321' => 'https://www.example.com/competitor-product', // Replace with your actual custom field ID
 
 // You can include other fields as needed
 'COMMENTS' => 'Lead lost due to competitor product: ' . $competitorId,
 
 // Ensure required fields are included
 'TITLE' => 'Lost Lead - Updated via API',
 'NAME' => 'John',
 'LAST_NAME' => 'Doe',
 'PHONE' => '+1234567890',
 'EMAIL' => 'john.doe@example.com'
];

$result = $CrmRest->call('crm.lead.update', [
 'id' => $leadId,
 'fields' => $fields
]);

if ($result['result']) {
 echo "Lead updated successfully";
} else {
 echo "Error updating lead: " . $result['error_description'];
}
?>

JavaScript Example: Using Bitrix24 REST API with Fetch

// Bitrix24 REST API update using fetch
const updateLead = async (leadId, fields) => {
 const domain = 'your.bitrix24domain.com';
 const accessToken = 'your_access_token';
 
 const response = await fetch(`https://${domain}/rest/1/${accessToken}/crm.lead.update`, {
 method: 'POST',
 headers: {
 'Content-Type': 'application/json',
 },
 body: JSON.stringify({
 id: leadId,
 fields: {
 // Status field
 STATUS_ID: 'LOST',
 
 // Enumeration field (competitor product)
 'UF_CRM_1234567890': 45, // Replace with your actual custom field ID
 
 // URL field
 'UF_CRM_0987654321': 'https://www.example.com/competitor-product', // Replace with your actual custom field ID
 
 // Other required fields
 TITLE: 'Lost Lead - Updated via API',
 NAME: 'John',
 LAST_NAME: 'Doe',
 PHONE: '+1234567890',
 EMAIL: 'john.doe@example.com'
 }
 })
 });
 
 const data = await response.json();
 
 if (data.result) {
 console.log('Lead updated successfully');
 return data;
 } else {
 console.error('Error updating lead:', data.error_description);
 throw new Error(data.error_description);
 }
};

// Usage example
updateLead(123, {})
 .then(result => console.log(result))
 .catch(error => console.error(error));

cURL Example: Command Line API Call

#!/bin/bash
# Bitrix24 REST API update using cURL

DOMAIN="your.bitrix24domain.com"
ACCESS_TOKEN="your_access_token"
LEAD_ID=123

curl -X POST "https://${DOMAIN}/rest/1/${ACCESS_TOKEN}/crm.lead.update" \
-H "Content-Type: application/json" \
-d '{
 "id": "'${LEAD_ID}'",
 "fields": {
 "STATUS_ID": "LOST",
 "UF_CRM_1234567890": 45,
 "UF_CRM_0987654321": "https://www.example.com/competitor-product",
 "TITLE": "Lost Lead - Updated via API",
 "NAME": "John",
 "LAST_NAME": "Doe",
 "PHONE": "+1234567890",
 "EMAIL": "john.doe@example.com"
 }
}'

Error Handling Example

<?php
try {
 $result = $CrmRest->call('crm.lead.update', [
 'id' => $leadId,
 'fields' => $fields
 ]);
 
 if (!$result['result']) {
 // Handle API errors
 throw new \Exception($result['error_description']);
 }
 
 // Handle specific field validation errors
 if (isset($result['error'])) {
 foreach ($result['error'] as $error) {
 if (strpos($error['error'], 'required') !== false) {
 // Handle missing required field
 echo "Missing required field: " . $error['field'] . "\n";
 }
 }
 }
 
 echo "Lead updated successfully";
 
} catch (\Exception $e) {
 echo "Error updating lead: " . $e->getMessage();
 // Implement retry logic or other error handling as needed
}
?>

These examples demonstrate the proper format for updating multiple fields in Bitrix24 CRM leads using the REST API. Remember to replace the field IDs with your actual custom field IDs and ensure all required fields are included in your update request.

Sources

1. Bitrix24 REST API Documentation — Comprehensive API reference for Bitrix24 REST API implementation: https://apidocs.bitrix24.com/
2. Bitrix24 CRM Tutorials — Practical examples and use cases for CRM API operations: https://apidocs.bitrix24.com/tutorials/crm/index.html
3. Bitrix24 Helpdesk — Official support resources for developers working with Bitrix24 REST API: https://www.bitrix24.com/support/developing/rest-api/

Conclusion

Updating multiple fields in Bitrix24 CRM leads using the REST API requires careful attention to field formatting and data types. When setting a lead status to ‘LOST’ while simultaneously updating enumeration fields like competitor products and URL fields, you must use the correct value formats for each field type. The key to success is understanding that status fields use status IDs, enumeration fields require numeric IDs, and URL fields need complete URL strings.

To avoid common issues, always retrieve the lead’s current details before updating, ensure all required fields have values, and handle potential validation errors gracefully. The Bitrix24 REST API provides powerful capabilities for complex lead updates, but proper implementation is essential to maintain data integrity and avoid API errors.

By following the proper API structure and using the correct field formats, you can successfully update multiple fields in Bitrix24 CRM leads, including setting the status to ‘LOST’ while updating enumeration and URL fields. Remember to test your implementation thoroughly and handle errors appropriately to ensure reliable CRM data management through the REST API.