Get a list of users with personal data search user.search

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

Scope: user, user_brief, user_basic

Who can execute the method: any user

Searches for users by first name, last name, middle name, department name, and job title.

The list of Bitrix24 user fields that will be retrieved as a result of the method execution depends on the scope of the application/webhook. The fields available in each version are listed in the User Scope Versions article.

The method inherits the behavior of the user.get method; all parameters from this function are also available.

Method Parameters

Required parameters are marked with *

Name `type`	Description
FILTER `object`	Object containing search fields (detailed description)
sort `string`	Field used to sort the results. Sorting works for all fields from user.add. The default value is `ID`
order `string`	Sorting direction: `ASC` — ascending `DESC` — descending The default value is `ASC`
ADMIN_MODE `boolean`	Enables administrator mode for retrieving user data. The parameter applies only when the request is made by an administrator. The default value is `false`
select `array`	An array with the names of the fields to return in the response. Without this parameter, the method returns all fields available to the application or webhook scope. When selecting, use masks: `` — all available fields `UF_` — all available custom fields, including those created in Bitrix24 The method skips fields that are unavailable to the scope or do not exist, without returning an error
start `integer`	The parameter is used to manage pagination. The result page size is always static: 50 records. To select the second page of results, you must pass the value `50`. To select the third page of results — the value `100` and so on. Formula for calculating the value of the `start` parameter: `start = (N - 1) * 50`, where `N` is the desired page number. The default value is `0`

The FILTER Parameter

Name `type`	Description
FIND `string`	Search string applied simultaneously to the first name, last name, middle name, job title, and department name
NAME `string`	User's first name
LAST_NAME `string`	User's last name
SECOND_NAME `string`	User's middle name
WORK_POSITION `string`	User's job title
UF_DEPARTMENT_NAME `string`	Department name
USER_TYPE `string`	User type. Possible values: `employee` — employee `extranet` — extranet user `email` — email user

To search across personal data, pass only FIND. To search by specific fields, omit FIND and specify one or more of the following fields: NAME, LAST_NAME, SECOND_NAME, WORK_POSITION, UF_DEPARTMENT_NAME.

The method automatically selects full-text search or a beginning-of-string search using USER_NAME LIKE "Text%". A beginning-of-string search is faster than a two-sided LIKE "%text%" or left-sided LIKE "%text" search because the database fields are indexed.

Code Examples

How to Use Examples in Documentation

cURL (Webhook)

cURL (OAuth)

JS (TS)

JS (UMD)

Python

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{
            "FILTER": {
                "FIND": "Klaus"
            }
        }' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/user.search

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{
            "FILTER": {
                "FIND": "Klaus"
            },
            "auth": "**put_access_token_here**"
        }' \
        https://**put_your_bitrix24_address**/rest/user.search

// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of each user object returned in result[]
        type UserItem = {
          ID: string
          ACTIVE: boolean
          NAME: string
          LAST_NAME: string
          SECOND_NAME?: string
          EMAIL: string
          LAST_LOGIN: ISODate | ''
          DATE_REGISTER: ISODate | ''
          IS_ONLINE: string
          PERSONAL_BIRTHDAY?: ISODate | ''
          WORK_POSITION?: string
          UF_DEPARTMENT?: number[]
          USER_TYPE: 'employee' | 'extranet' | 'email'
        }
        
        try {
          const response = await $b24.actions.v2.call.make<UserItem[]>({
            method: 'user.search',
            params: {
              FILTER: {
                FIND: 'Klaus',
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Users found on this page:', result.length, result)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }

<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function searchUsers() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'user.search',
                params: {
                  FILTER: {
                    FIND: 'Klaus',
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Users found on this page:', result.length, result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', searchUsers)
        </script>

from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.user.search(
                filter={
                    "FIND": "Klaus",
                },
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")

try {
            $response = $b24Service
                ->core
                ->call(
                    'user.search',
                    [
                        'FILTER' => [
                            'FIND' => 'Klaus',
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error searching for users: ' . $e->getMessage();
        }

BX24.callMethod(
            "user.search",
            {
                "FILTER": {
                    "FIND": "Klaus"
                }
            },
            function(result)
            {
                if (result.error())
                {
                    console.error(result.error());
                    return;
                }
        
                console.dir(result.data());
        
                if (result.more())
                {
                    result.next();
                }
            }
        );

require_once('crest.php');
        
        $result = CRest::call(
            'user.search',
            [
                "FILTER" => [
                    "FIND" => "Klaus",
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Response Handling

HTTP status: 200

    {
                "result": [
                    {
                        "ID": "3",
                        "ACTIVE": true,
                        "NAME": "John",
                        "LAST_NAME": "Smith",
                        "EMAIL": "test@gmail.com",
                        "LAST_LOGIN": "2024-07-24T09:01:55+00:00",
                        "DATE_REGISTER": "2024-07-22T00:00:00+00:00",
                        "IS_ONLINE": "N",
                        "TIMESTAMP_X": {
                        },
                        "LAST_ACTIVITY_DATE": {
                        },
                        "PERSONAL_GENDER": "",
                        "PERSONAL_BIRTHDAY": "",
                        "WORK_POSITION": "",
                        "UF_EMPLOYMENT_DATE": "",
                        "UF_DEPARTMENT": [1],
                        "USER_TYPE": "employee"
                    }
                ],
                "total": 1,
                "time": {
                    "start": 1721913235.39648,
                    "finish": 1721913235.45078,
                    "duration": 0.05430006980896,
                    "processing": 0.0187909603118897,
                    "date_start": "2024-07-25T13:13:55+00:00",
                    "date_finish": "2024-07-25T13:13:55+00:00",
                    "operating": 0
                }
            }

Returned Data

Name `type`	Description
result `object[]`	Array of users that match the search conditions (detailed description). The set of fields depends on the scope and the `select` parameter
total `integer`	Total number of records found
next `integer`	Offset for the next page. The field is omitted on the last page
time `time`	Information about the request execution time

The result Object

The method returns fields available to the application or webhook scope. You can retrieve the complete list using the user.fields method.

Name `type`	Description
ID `integer`	User ID
ACTIVE `boolean`	User activity indicator
NAME `string`	User's first name
LAST_NAME `string`	User's last name
SECOND_NAME `string`	User's middle name
EMAIL `string`	Email address
LAST_LOGIN `datetime`	Date and time of the last login
DATE_REGISTER `datetime`	Registration date and time
IS_ONLINE `string`	Online activity indicator. Possible values: `Y` — the user is online `N` — the user is not online
PERSONAL_BIRTHDAY `date`	Date of birth
WORK_POSITION `string`	Job title
UF_DEPARTMENT `integer[]`	User's department IDs
USER_TYPE `string`	User type: `employee`, `extranet`, or `email`

Error Handling

The method does not return specific errors.

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

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 Learning

Was the article helpful?

Get User List by Filter

Get User Fields

Get a list of users with personal data search user.search

Method ParametersMethod Parameters

The FILTER ParameterThe FILTER Parameter

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

The result ObjectThe result Object

Error HandlingError Handling

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning