How to Use Examples in the Documentation

On method pages in the API Reference, examples are grouped in the "Code Examples" block. The tabs show a method call via cURL and via the official Bitrix24 SDKs — libraries for different programming languages. Most often, the code in a tab is a call fragment rather than a complete project. Such a fragment does not include library installation, connection to Bitrix24, or real parameter values.

To make an example work, choose a tab for your environment, replace placeholders like **put_your_webhook_here** with your own values, and create a connection object for the SDK.

The How a Request Is Executed article explains how an HTTP request to the REST API is structured.

Which Tab to ChooseWhich Tab to Choose

The set of tabs varies across pages: each page contains only the examples prepared for that specific method. If there is no B24PhpSDK example, use CRest or construct the call based on the method parameter descriptions.

Tab labels are not formatted identically everywhere: a tab with a B24JsSDK example might be labeled JS.

Check the label against the code: you can recognize a tab by the object used for the call. The objects of each SDK are listed in the table in the What to Add to Make an Example Work section.

cURL tabs are suitable when you need to test a method, view a raw response, or call the API where you cannot connect an SDK, such as from a terminal or a third-party service. For a production integration, use an SDK: it handles authorization and parses the response.

Additional capabilities differ between SDKs: for example, B24JsSDK refreshes tokens and respects request limits on its own. B24GoSDK retries a request by default when the limit is exceeded and refreshes tokens once the client is configured. B24PhpSDK, BX24.js, and CRest do not support REST 3.0 methods. If multiple SDKs fit, compare them in the SDK Overview.

What to Substitute for PlaceholdersWhat to Substitute for Placeholders

Instead of real values, examples use placeholders in double asterisks, such as **put_your_webhook_here**. Replace the entire placeholder, including the asterisks: they must not be part of the value.

An inbound webhook URL looks like this: https://your-company.bitrix24.com/rest/1/8v5m0dmbxs2ky7wq/. Here 1 is the user identifier, and 8v5m0dmbxs2ky7wq is the secret code.

How to Execute an Example Without LibrariesHow to Execute an Example Without Libraries

Examples in the cURL (Webhook) and cURL (OAuth) tabs do not require installation: simply replace the placeholders with your own values. The commands are written for Bash. In PowerShell on Windows, call curl.exe instead of curl, and adapt the \ line breaks and quotes to PowerShell rules.

The example below creates a deal with the crm.item.add method. It is a simplified version of the cURL (Webhook) tab from the method page. The entityTypeId parameter sets the CRM object type: the value 2 means a deal. The fields parameter contains only the title field. Bitrix24 fills in fields that have default values on its own.

The call requires the crm scope and permission to add deals. If the Validate required custom fields in REST option is enabled in the CRM settings, add the required custom fields to fields. Each run creates a new deal, so run the example on a test Bitrix24.

Request with placeholders:

curl -X POST \
        -H "Content-Type: application/json" \
        -d '{"entityTypeId":2,"fields":{"title":"New deal"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.item.add
        

The same request with substituted values:

curl -X POST \
        -H "Content-Type: application/json" \
        -d '{"entityTypeId":2,"fields":{"title":"New deal"}}' \
        https://your-company.bitrix24.com/rest/1/8v5m0dmbxs2ky7wq/crm.item.add
        

On the cURL (OAuth) tab, the address is shorter — it does not contain the user identifier or the webhook code, and the token is passed in the request body via the auth parameter:

curl -X POST \
        -H "Content-Type: application/json" \
        -d '{"entityTypeId":2,"fields":{"title":"New deal"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.item.add
        

The response is the same for both tabs. If the request succeeds, Bitrix24 returns the created deal in the result.item field and its identifier in the result.item.id field. The full response is on the method page.

Abbreviated response:

{
            "result": {
                "item": {
                    "id": 16,
                    "title": "New deal",
                    "categoryId": 0,
                    "stageId": "NEW",
                    "assignedById": 1
                }
            },
            "time": {
                "duration": 1.9278500080108643
            }
        }
        

What to Add to Make an Example WorkWhat to Add to Make an Example Work

Most SDK examples begin immediately with a method call and refer to a connection object that is not present in the example itself. Create the connection object following the instructions on the relevant SDK page, then insert the fragment from the documentation. What the example contains and what to prepare yourself:

Examples in the JS (TS), JS (UMD), and JS tabs are designed for an application opened in a frame inside the Bitrix24 interface. In these examples, $b24 is a B24Frame object created by the initializeB24Frame function. Server-side code on Node.js needs a different connection class — B24Hook or B24OAuth. They are described in the Installing and Using B24JsSDK article.

In almost all examples, the link to the UMD build is pinned to the first major version, @bitrix24/b24jssdk@1. If the project is running on the second version, replace the number in the link with @2.

If you install B24JsSDK from npm, check that its version matches the example. Version 3.0.0 removed the $b24.callMethod, $b24.callListMethod, $b24.fetchListMethod, $b24.callBatch, and $b24.callBatchByChunk methods, while examples on many pages still use them. To make such an example work, install the second version of the SDK or replace the call with $b24.actions.v2, as described in the Method Invocation Methods section.

Response parsing also differs between tools. A request via cURL returns raw JSON, whereas each SDK wraps it in its own way. The response structure is described on the method page in the "Response Handling" section. The SDK page explains how to access the data.

Field and Parameter NamesField and Parameter Names

Copy field names from the example and from the "Method Parameters" section without changes. Different method groups follow different naming conventions:

• Universal CRM Methods, such as crm.item.add, use camelCase — title, stageId, entityTypeId
• Earlier methods, such as crm.deal.add, use uppercase with underscores — TITLE, STAGE_ID

Universal methods crm.item.* also accept uppercase names with underscores, but you should not rely on this.

CRM methods from both groups belong to the previous API version and ignore an unknown field name in fields: the value of such a field is not saved, and no error is returned because of it. REST 3.0 methods return an error for such a field.

Errors and DiagnosticsErrors and Diagnostics

First, check whether the method is marked as deprecated. If it is, its page names a replacement — use it.

The Errors and Diagnostics section of the first-request article covers common call errors, such as an incorrect webhook URL or a missing scope. When running examples, the following errors are more common:

Other codes are listed in the Error Codes article.

Continue LearningContinue Learning

• How to Make Your First API Request
• How a Request Is Executed
• How to Execute a Batch Request
• SDK for Bitrix24 Development
• Tutorials: Ready-to-Use REST API Scenarios