User Scope Versions

The user scope comes in three versions. These are three independent codes: user_brief, user_basic, and user. The version determines which employee profile fields the methods return. It also determines whether an application can invite employees and modify their profiles. Versions let you grant an application only the personal data its scenario requires.

All three versions are available in cloud Bitrix24. In on-premise Bitrix24, they were introduced in the module version Rest 21.600.0. Before that version, only the user scope is available.

Scopes are selected in the settings of an application or a webhook — the procedure is described in the Available Scopes in Bitrix24 article. For profile field values and the response format, see the user.get and user.fields method pages.

How the Versions DifferHow the Versions Differ

The versions are nested: user_basic includes all user_brief fields, and user includes all user_basic fields.

The minimum version does not hide all personal data. In user_brief, contact details are closed first of all: e-mail, personal and work phone numbers, street and postal code, links to external profiles. At the same time, gender, date of birth, and the employee photo are available in all three versions. The full composition of each version is in the tables below.

The user version adds three fields to user_basic: LAST_LOGIN, PERSONAL_WWW, and PERSONAL_ICQ. Its main difference lies not in the fields, but in write operations.

How to Select a VersionHow to Select a Version

Request the narrowest version that is sufficient for your scenario: the application receives less personal data, and the Bitrix24 administrator sees a lower access level in the permission list.

How the Version Restriction WorksHow the Version Restriction Works

The restriction applies to every call of the methods that read or modify a profile: user.fields, user.current, user.get, user.search, user.add, and user.update.

• Each of these methods returns and accepts only the fields permitted by the version.
• The user.online and user.counters methods are available in all three versions: they do not return profile fields.
• Bitrix24 skips a field that is not in the permitted list. Such a field is ignored in the select and filter parameters, it is absent from the response, and the method does not return an error.
• The user.add and user.update methods work only in the user version. In the user_brief and user_basic versions, a call returns the insufficient_scope error with the description The request requires higher privileges than provided by the access token. The response is identical for an application and a webhook.
• The scope does not cancel the employee permission check. New employees can be invited with the user.add method by an administrator, and in cloud Bitrix24 also by an employee who has been granted the invitation permission. Without administrator permissions, the user.update method modifies only the employee's own profile — the ACTIVE and UF_DEPARTMENT fields are not retained in this case.
• An application receives the onUserAdd event in all three versions. Only the fields permitted by the version remain in the new employee data.
• The broadest of the granted versions determines the access. For example, if user_brief and user_basic are granted, user_basic applies.
• The selected version does not affect the user.userfield.* methods: they manage custom field configurations and work in the separate user.userfield scope.

To see the actual list of fields for the granted version, call the user.fields method.

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

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{}' \
        https://**put_your_bitrix24_address**/rest/user.fields
        

The method returns field codes and their names — only those permitted by the granted version. The composition of the response identifies the version:

• the EMAIL field is absent — user_brief
• EMAIL is present, but LAST_LOGIN is absent — user_basic
• LAST_LOGIN is present — user

Custom Profile FieldsCustom Profile Fields

Fields with the UF_USR_ prefix are not included in the version lists.

• In the user version, they are available for reading and writing without additional conditions.
• In the user_brief and user_basic versions, they can only be read, provided that the application has been granted the user.userfield scope. A value cannot be retained in such a field: this requires the user.update method, which works only in the user version.

Such fields are created and configured with the user.userfield.* methods.

Which Fields Are AvailableWhich Fields Are Available

The tables list the standard profile fields, including the fields with the UF_ prefix that exist in Bitrix24 by default. Yes means the field is available for reading in this version, No means it is unavailable. Fields are retained only by the user.add and user.update methods, so in the user_brief and user_basic versions any field is available for reading only.

The LAST_LOGIN, DATE_REGISTER, and IS_ONLINE fields are available for reading only. The user.add and user.update methods do not retain them even in the user version.

Identification and StatusIdentification and Status

Name, Position, DepartmentName, Position, Department

ContactsContacts

AddressesAddresses

Personal and Professional DataPersonal and Professional Data

Continue LearningContinue Learning

• Available Scopes in Bitrix24
• Get user fields user.fields
• Get a list of users by filter user.get
• Users: Overview of Methods