Call a Bitrix24 Method BX24.callMethod

Choose a tool for developing with an AI agent:

use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

void BX24.callMethod(
            String method,
            Object params[,
                Function callback
            ]
        );

The BX24.callMethod function calls a Bitrix24 method on behalf of the user who opened the application. The library automatically adds authorization data to the request and converts the params object into a POST request string.

Values in params can be strings, numbers, arrays, nested objects, and dates. The library passes a date as a string in ISO 8601 format. Instead of a value, you can pass a form field element: for a regular field, the library takes its value, and for an <input type="file"> field without the multiple attribute, the selected file.

The function returns nothing: the result is passed to the callback function. If you call BX24.callMethod before BX24.init, the library defers the request until initialization completes.

The function works only inside the frame of an application and only when the BX24.js library is loaded — the Library Overview describes how to load it.

Parameters

Required parameters are marked with *

Name `type`	Description
method* `string`	Bitrix24 method name, for example, user.get
params* `object`	Parameters of the called method. They are listed on the page of that method. If the method has no parameters, pass an empty object `{}`: `callback` must be the third parameter of the function
callback `function`	Function that receives the request result — an ajaxResult object. Without it, the request is executed, but you cannot find out the result

Code Examples

How to Use Examples in Documentation

Retrieve the user with ID 10. The application needs one of the following scopes for the user.get method: user, user_brief, or user_basic:

BX24.init(() => {
            BX24.callMethod('user.get', { ID: 10 }, (result) => {
                if (result.error())
                {
                    console.error(result.error());
                }
                else if (result.data())
                {
                    const user = result.data()[0];
                    if (user)
                    {
                        alert('User №' + user.ID + ' is named ' + user.NAME);
                    }
                }
            });
        });

Retrieve a list of users page by page. The user.get method returns up to 50 records per call. While result.more() returns true, the result.next() method requests the next page and passes it to the same handler. You cannot pass a non-zero start in params: the library removes it from the request and from the params object itself.

BX24.init(() => {
            BX24.callMethod('user.get', { sort: 'ID', order: 'ASC' }, (result) => {
                if (result.error())
                {
                    console.error(result.error().toString());
                    return;
                }
        
                console.log(result.data());
                if (result.more())
                {
                    result.next();
                }
            });
        });

Upload an employee photo using the user.update method when the user selects a file in a form field. The library reads the selected file and passes it in the PERSONAL_PHOTO parameter. The method requires the user scope, and only an administrator can change another employee's profile:

// <input type="file" id="photo"> — a field on the application page
        BX24.init(() => {
            const photo = document.getElementById('photo');
        
            photo.addEventListener('change', () => {
                if (photo.files.length !== 1)
                {
                    return;
                }
        
                BX24.callMethod('user.update', {
                    ID: 10,
                    PERSONAL_PHOTO: photo,
                }, (result) => {
                    if (result.error())
                    {
                        console.error(result.error().toString());
                        return;
                    }
        
                    console.log(result.data()); // true
                });
            });
        });

Response Handling

The callback function receives an ajaxResult object. Its answer property stores the Bitrix24 response. An abbreviated example for the user.get method:

{
            "result": [
                {
                    "ID": "10",
                    "ACTIVE": true,
                    "NAME": "Klaus",
                    "LAST_NAME": "Weber",
                    "UF_DEPARTMENT": [1]
                }
            ],
            "total": 1,
            "time": {
                "start": 1790283114,
                "finish": 1790283114.0253,
                "duration": 0.0253,
                "processing": 0,
                "date_start": "2026-09-24T20:51:54+00:00",
                "date_finish": "2026-09-24T20:51:54+00:00"
            }
        }

If the list has a next page, the response also contains the next field — the start value for that page. The object's methods make the response easier to read.

ajaxResult Object Methods

Method	What it returns
`data()`	The `result` field of the response: an array, an object, or a scalar value, depending on the called method. If an error occurred, it returns `undefined`
`error()`	An error object, or `undefined` if there is no error. The structure of the error object is described in the Error Handling section
`error_description()`	The error message, or `undefined` if there is no error
`more()`	`true` if the list has a next page
`total()`	The total number of records in the list. If the method did not return it, `total()` returns `NaN`
`next(cb)`	Requests the next page of the list and passes it to the `cb` function or, if it is not provided, to the original handler. The `cb` function also becomes the handler for subsequent pages. The `next(cb)` method returns `false` if there are no more pages, and `undefined` if the request has been sent

In addition to methods, the object has properties: answer — the Bitrix24 response, status — the HTTP status of the response, query — a copy of the request settings with the method, data, and callback fields. The library adds its own fields to answer. If Bitrix24 returns an error, these include an error object with a reference to the response itself, and JSON.stringify(result.answer) throws an exception. The request execution time is stored in result.answer.time, and there is no separate method for it. The time fields are described in the Time Object section.

Error Handling

The library passes an error returned by Bitrix24 to callback. The result.error() method returns an error object: the ex field contains the Bitrix24 response with the error code and message, and the status field contains the HTTP status. The main fields of the object:

{
            "status": 401,
            "ex": {
                "error": "insufficient_scope",
                "error_description": "The request requires higher privileges than provided by the access token"
            }
        }

The error code is available in result.error().ex.error, and the message in result.error().ex.error_description. The getError() method returns the entire ex object, the result.error().status property and the getStatus() method return the HTTP status, and the toString() method returns a formatted string containing the code, message, and status.

Error codes depend on the called method and are described on its page.

Name `type`	Description
error `string`	String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only `error_description` shows the reason
error_description `string`	Error message for the developer. Do not show it to the end user without processing

The following are not passed to callback:

a response with a 5xx status, a network failure, and a response that could not be parsed as JSON. The library throws a Query error! exception from the asynchronous request handler, so a try/catch around the call does not catch it
the expired_token error. The library refreshes the authorization itself and retries the request, and callback receives the result of the retry

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`429`	`OPERATION_TIME_LIMIT` Method is blocked due to operation time limit	The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit
`401`	`NO_AUTH_FOUND` Wrong authorization data	The request contains no authorization data: neither an access token nor a webhook code was passed
`401`	`INVALID_REQUEST` Https required	Methods are called over the HTTPS protocol only
`401`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support
`401`	`ACCESS_DENIED` REST is available only on commercial plans	REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — `REST is available only by subscription`
`401`	`INVALID_CREDENTIALS` Invalid request credentials	No active webhook with the specified user identifier and secret code was found
`404`	`ERROR_METHOD_NOT_FOUND` Method not found!	No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope
`401`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with `provided by the access token`
`401`	`expired_token` The access token provided has expired	The access token has expired
`401`	`user_access_error` The user does not have access to the application	The application is installed, but the Bitrix24 administrator has granted access to it only to specific users
`403`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue your exploration

Was the article helpful?

Calling REST Methods

Send Batch of Requests

Call a Bitrix24 Method BX24.callMethod

ParametersParameters

Code ExamplesCode Examples

Response HandlingResponse Handling

ajaxResult Object MethodsajaxResult Object Methods

Error HandlingError Handling

Statuses and System Error CodesStatuses and System Error Codes

Continue your explorationContinue your exploration