Bitrix24 Users API
The Users API from Bitrix24 — 8 operation(s) for users.
OpenAPI Specification
openapi: 3.0.3
info:
title: Bitrix24 REST BIconnector Users API
version: 1.0.0
description: 'Bitrix24 REST API provides access to CRM, tasks, drive, chats, telephony, e-commerce, automation, and other modules. Documentation: https://apidocs.bitrix24.com'
contact:
name: Bitrix24 Developer Support
url: https://apidocs.bitrix24.com/support.html
license:
name: MIT
url: https://github.com/bitrix-tools/b24-rest-docs/blob/main/LICENSE
x-logo:
url: https://apidocs.bitrix24.com/_images/bitrix24logo.svg
servers:
- url: https://{portal}.bitrix24.com/rest
description: Your Bitrix24 portal (cloud)
variables:
portal:
default: your-portal
description: Subdomain of your Bitrix24 portal
- url: https://{host}/rest
description: On-Premise Bitrix24 installation
variables:
host:
default: your-bitrix24.example.com
description: Host of your on-premise installation
security:
- AccessToken: []
tags:
- name: Users
paths:
/user.current:
post:
summary: Get Information About the Current User user.current
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `user.current` retrieves information about the [current](*current_key*) user. The list of user fields in Bitrix24 that will be obtained as a result of executing the method depends on the application's/webhook's scope. Details about user data access can be found in the [article](index.md). The method has no parameters. However, by making a REST request using data from `$_REQUEST` to the domain `DOMAIN` and adding `AUTH_ID` to the request for access to Bitrix24, you can find out which user opened the page in the context of Bitrix24.
operationId: user_current
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/user-current.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
result:
type: object
description: '| The root element of the response that contains information about the user ||'
time:
type: string
description: '| Information about the request execution time ||'
application/x-www-form-urlencoded:
schema:
type: object
properties:
result:
type: object
description: '| The root element of the response that contains information about the user ||'
time:
type: string
description: '| Information about the request execution time ||'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user
/user.fields:
post:
summary: Get User Fields user.fields
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The `user.fields` method allows you to retrieve a list of user field names. The method returns a standard list of fields, and the use of custom fields is not supported. The list of user fields in Bitrix24 that will be obtained as a result of executing the method depends on the application's/webhook's scope. Details about accessing user data can be found in the [article](index.md). Without parameters.
operationId: user_fields
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/user-fields.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
result:
type: object
description: '| Root element of the response containing user fields ||'
time:
type: string
description: '| Information about the request execution time ||'
application/x-www-form-urlencoded:
schema:
type: object
properties:
result:
type: object
description: '| Root element of the response containing user fields ||'
time:
type: string
description: '| Information about the request execution time ||'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user
/user.search:
post:
summary: Get a List of Users with Search by Personal Data user.search
description: 'If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The `user.search` method allows you to retrieve a list of users with accelerated search based on personal data (first name, last name, patronymic, department name, job title). It operates in two modes: quickly using **Fulltext Index** and a slower option through [right LIKE](*key_right LIKE) (support is determined automatically). The list of user fields in Bitrix24 that will be returned as a result of executing the method depends on the application''s/webhook''s scope. Details about accessing user data can be found in the [article](index.md). The method inherits the behavior of the [user.get](./user-get.md) method, and all parameters from this function are also available.'
operationId: user_search
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/user-search.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
FILTER:
type: string
description: '| The array can contain fields in any combination:'
sort:
type: string
description: '| The field by which the results are sorted. Sorting works on all fields from user.add ||'
order:
type: string
description: '| Sorting direction:'
ADMIN_MODE:
type: boolean
description: '| Key for operation in administrator mode. Used to retrieve data about any users ||'
start:
type: integer
description: '| This parameter is used for managing pagination.'
application/x-www-form-urlencoded:
schema:
type: object
properties:
FILTER:
type: string
description: '| The array can contain fields in any combination:'
sort:
type: string
description: '| The field by which the results are sorted. Sorting works on all fields from user.add ||'
order:
type: string
description: '| Sorting direction:'
ADMIN_MODE:
type: boolean
description: '| Key for operation in administrator mode. Used to retrieve data about any users ||'
start:
type: integer
description: '| This parameter is used for managing pagination.'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user
/user.userfield.add:
post:
summary: Add Custom Field user.userfield.add
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `user.userfield.add` adds a custom field.
operationId: user_userfield_add
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/userfields/user-userfield-add.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
fields:
type: object
description: '| Values of the fields to add a new custom field ||'
FIELD_NAME:
type: string
description: '| Name (code) of the field. Prefixed with `UF_USR_`'
USER_TYPE_ID:
type: string
description: '| Type of the custom field. Possible values:'
XML_ID:
type: string
description: '| External code ||'
SORT:
type: integer
description: '| Sorting order ||'
MULTIPLE:
type: boolean
description: '| Is the field multiple. Possible values:'
MANDATORY:
type: boolean
description: '| Is the custom field mandatory. Possible values:'
SHOW_FILTER:
type: boolean
description: '| Show the field in the list filter. Possible values:'
SHOW_IN_LIST:
type: boolean
description: '| Show the field in the list. Possible values:'
SETTINGS:
type: object
description: '| Object in the format `{"field_1": "value_1", ... "field_N": "value_N"}` for passing additional settings for custom fields. Settings are described below ||'
EDIT_FORM_LABEL:
type: string
description: '| Label in the edit form. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_COLUMN_LABEL:
type: string
description: '| Column header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_FILTER_LABEL:
type: string
description: '| Filter header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
ERROR_MESSAGE:
type: string
description: '| Error message for invalid input. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
HELP_MESSAGE:
type: string
description: '| Help text for the field. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LABEL:
type: string
description: '| Default name of the custom field.'
required:
- fields
- FIELD_NAME
- USER_TYPE_ID
application/x-www-form-urlencoded:
schema:
type: object
properties:
fields:
type: object
description: '| Values of the fields to add a new custom field ||'
FIELD_NAME:
type: string
description: '| Name (code) of the field. Prefixed with `UF_USR_`'
USER_TYPE_ID:
type: string
description: '| Type of the custom field. Possible values:'
XML_ID:
type: string
description: '| External code ||'
SORT:
type: integer
description: '| Sorting order ||'
MULTIPLE:
type: boolean
description: '| Is the field multiple. Possible values:'
MANDATORY:
type: boolean
description: '| Is the custom field mandatory. Possible values:'
SHOW_FILTER:
type: boolean
description: '| Show the field in the list filter. Possible values:'
SHOW_IN_LIST:
type: boolean
description: '| Show the field in the list. Possible values:'
SETTINGS:
type: object
description: '| Object in the format `{"field_1": "value_1", ... "field_N": "value_N"}` for passing additional settings for custom fields. Settings are described below ||'
EDIT_FORM_LABEL:
type: string
description: '| Label in the edit form. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_COLUMN_LABEL:
type: string
description: '| Column header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_FILTER_LABEL:
type: string
description: '| Filter header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
ERROR_MESSAGE:
type: string
description: '| Error message for invalid input. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
HELP_MESSAGE:
type: string
description: '| Help text for the field. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LABEL:
type: string
description: '| Default name of the custom field.'
required:
- fields
- FIELD_NAME
- USER_TYPE_ID
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user.userfield
/user.userfield.delete:
post:
summary: Delete User Field user.userfield.delete
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `user.userfield.delete` removes a user field.
operationId: user_userfield_delete
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/userfields/user-userfield-delete.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: '| Identifier of the user field.'
required:
- id
application/x-www-form-urlencoded:
schema:
type: object
properties:
id:
type: integer
description: '| Identifier of the user field.'
required:
- id
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user.userfield
/user.userfield.file.get:
post:
summary: Get File from User Field user.userfield.file.get
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The page is hidden from the menu, and the method is not operational. Some data may be missing here — we will complete it shortly. - It may be necessary to list parameters or fields in a table.
operationId: user_userfield_file_get
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/userfields/user-userfield-file-get.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
application/x-www-form-urlencoded:
schema:
type: object
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user.userfield
/user.userfield.list:
post:
summary: Get a list of custom fields user.userfield.list
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `user.userfield.list` retrieves a list of custom fields based on the filter.
operationId: user_userfield_list
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/userfields/user-userfield-list.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
order:
type: string
description: '\|`array` | Sorting of the selected custom fields in the format `{"field_1": "order_1", ... "field_N": "order_N"}`.'
filter:
type: array
items: {}
description: '| Filter for the selected custom fields in the format `{"field_1": "value_1", ... "field_N": "value_N"}`.'
application/x-www-form-urlencoded:
schema:
type: object
properties:
order:
type: string
description: '\|`array` | Sorting of the selected custom fields in the format `{"field_1": "order_1", ... "field_N": "order_N"}`.'
filter:
type: array
items: {}
description: '| Filter for the selected custom fields in the format `{"field_1": "value_1", ... "field_N": "value_N"}`.'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user.userfield
/user.userfield.update:
post:
summary: Update User Field user.userfield.update
description: If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the [MCP server](../../../ai-tools/mcp.md) so that the assistant can utilize the official REST documentation. The method `user.userfield.update` updates a user field.
operationId: user_userfield_update
tags:
- Users
externalDocs:
url: https://apidocs.bitrix24.com/api-reference/user/userfields/user-userfield-update.html
description: Official Documentation
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: '| Identifier of the user field.'
fields:
type: object
description: '| Values of the fields to update the user field ||'
XML_ID:
type: string
description: '| External code ||'
SORT:
type: integer
description: '| Sort order ||'
MANDATORY:
type: boolean
description: '| Whether the user field is mandatory. Possible values:'
SHOW_FILTER:
type: boolean
description: '| Whether to show the field in the list filter. Possible values:'
SHOW_IN_LIST:
type: boolean
description: '| Whether to show the field in the list. Possible values:'
SETTINGS:
type: object
description: '| An object in the format `{"field_1": "value_1", ... "field_N": "value_N"}` for passing additional settings for user fields. Settings are described below ||'
EDIT_FORM_LABEL:
type: string
description: '| Label in the edit form. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_COLUMN_LABEL:
type: string
description: '| Column header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_FILTER_LABEL:
type: string
description: '| Filter header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
ERROR_MESSAGE:
type: string
description: '| Error message for invalid input. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
HELP_MESSAGE:
type: string
description: '| Help text for the field. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LABEL:
type: string
description: '| Default name of the user field.'
required:
- id
application/x-www-form-urlencoded:
schema:
type: object
properties:
id:
type: integer
description: '| Identifier of the user field.'
fields:
type: object
description: '| Values of the fields to update the user field ||'
XML_ID:
type: string
description: '| External code ||'
SORT:
type: integer
description: '| Sort order ||'
MANDATORY:
type: boolean
description: '| Whether the user field is mandatory. Possible values:'
SHOW_FILTER:
type: boolean
description: '| Whether to show the field in the list filter. Possible values:'
SHOW_IN_LIST:
type: boolean
description: '| Whether to show the field in the list. Possible values:'
SETTINGS:
type: object
description: '| An object in the format `{"field_1": "value_1", ... "field_N": "value_N"}` for passing additional settings for user fields. Settings are described below ||'
EDIT_FORM_LABEL:
type: string
description: '| Label in the edit form. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_COLUMN_LABEL:
type: string
description: '| Column header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LIST_FILTER_LABEL:
type: string
description: '| Filter header in the list. You can pass a string or an object with labels by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
ERROR_MESSAGE:
type: string
description: '| Error message for invalid input. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
HELP_MESSAGE:
type: string
description: '| Help text for the field. You can pass a string or an object with texts by languages in the format `{"de": "...", "en": "..."}`. When passing a string, the value will be set for all languages ||'
LABEL:
type: string
description: '| Default name of the user field.'
required:
- id
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixResponse'
4XX:
description: Request error (400, 401, 403)
content:
application/json:
schema:
$ref: '#/components/schemas/BitrixError'
security:
- AccessToken: []
- OAuth2:
- user.userfield
components:
schemas:
BitrixError:
type: object
description: Bitrix24 REST API error response
required:
- error
- error_description
properties:
error:
type: string
description: Error code
example: ACCESS_DENIED
error_description:
type: string
description: Human-readable error description
example: Access denied.
BitrixTime:
type: object
description: Request execution time information
properties:
start:
type: number
format: double
finish:
type: number
format: double
duration:
type: number
format: double
processing:
type: number
format: double
date_start:
type: string
format: date-time
date_finish:
type: string
format: date-time
operating_reset_at:
type: integer
operating:
type: number
format: double
BitrixResponse:
type: object
description: Standard Bitrix24 REST API response
properties:
result:
description: Method execution result
total:
type: integer
description: Total number of records (for list methods)
next:
type: integer
description: Next offset for pagination
time:
$ref: '#/components/schemas/BitrixTime'
securitySchemes:
AccessToken:
type: apiKey
in: query
name: auth
description: OAuth 2.0 access_token or incoming webhook token
OAuth2:
type: oauth2
description: OAuth 2.0 authorization
flows:
authorizationCode:
authorizationUrl: https://oauth.bitrix.info/oauth/authorize/
tokenUrl: https://oauth.bitrix.info/oauth/token/
scopes:
crm: CRM — leads, deals, contacts, companies, smart processes
task: Tasks and projects
disk: Drive — files and folders
im: Chats and notifications
imbot: Chatbots
imopenlines: Open Lines — messenger connectors
telephony: Telephony
sale: E-Commerce — orders, shipments
catalog: Trade Catalog — products, prices
calendar: Calendar
bizproc: Business processes and robots
user: Users
department: Company structure
timeman: Time tracking
landing: Sites and landing pages
pay_system: Payment systems
cashbox: Online cash registers
delivery: Delivery services
documentgenerator: Document generator
lists: Universal lists
entity: Data storage
log: News feed
sonet_group: Workgroups and projects
mailservice: Mail services
messageservice: Message providers (SMS)
biconnector: BIconnector — BI analytics
ai_admin: CoPilot / AI
sign.b2e: Signature — e-document signing
vote: Polls and voting
booking: Online booking
userconsent: User consent agreements
userfieldconfig: Custom field settings
basic: Basic access
placement: Widget placements
rpa: Robots process automation
sonet: Social network
intranet: Intranet
socialnetwork: Social network
workgroups: Workgroups
salescenter: Sales center
main: Main module
imconnector: IM connector
user.userfield: User custom fields
user_basic: Basic user access
userfieldconfig, module scope: Custom field config
externalDocs:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitrix24/refs/heads/main/openapi/bitrix24-users-api-openapi.yml