لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/humanresources/employees.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Employees

Search employees by name, get their subordinates, the total number of employees, and the list of those who belong to several departments at once.

Bitrix24 API: humanresources.employee.* Scope: humanresources

Search employees

POST /v1/humanresources/employees/search

Returns employees in your Bitrix24 account whose name matches the provided search query. Useful for finding an employee identifier by name before calling other operations in this section.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionString to search by employee name
FieldnodeId Typenumber Requiredno DescriptionLimit the search to employees of a single node. List: GET /v1/humanresources/nodes?type=DEPARTMENT

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/employees/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "John" }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/employees/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "John" }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/employees/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'John' }),
})

const { success, data } = await res.json()
console.log(`Found ${data.items.length} employees`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/employees/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'John' }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.items Typearray DescriptionArray of found employees. Empty if there are no matches
Fielddata.items[].userId Typenumber DescriptionEmployee identifier
Fielddata.items[].name Typestring DescriptionEmployee name
Fielddata.items[].workPosition Typestring DescriptionEmployee position. Empty string if the position is not set
Fielddata.items[].avatar Typestring DescriptionURL of the employee's profile image
Fielddata.items[].url Typestring DescriptionRelative path to the employee's card in Bitrix24
Fielddata.items[].departments Typearray DescriptionDepartments the employee belongs to
Fielddata.items[].departments[].id Typenumber DescriptionDepartment identifier
Fielddata.items[].departments[].name Typestring DescriptionDepartment name
Fielddata.items[].teams Typearray DescriptionTeams the employee belongs to. The element structure matches departments (id, name)

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "userId": 1,
        "name": "John Brown",
        "workPosition": "",
        "avatar": "https://cdn.bitrix24.com/.../avatar.jpg",
        "url": "/company/personal/user/1/",
        "departments": [
          { "id": 1, "name": "Company" },
          { "id": 9, "name": "Division" },
          { "id": 11, "name": "Work group" },
          { "id": 23, "name": "Sales department" }
        ],
        "teams": []
      }
    ]
  }
}

Error response example

400 — the name field was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "MISSING_NAME",
        "message": "Parameter \"name\" is required."
      }
    ]
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe name field is missing — error.validation carries a MISSING_NAME entry
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the humanresources scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

An empty result is a success, not an error. If there are no matches by name, the response stays successful (success: true) and data.items comes back as an empty array.

See also