For AI agents: markdown of this page — /docs-content-en/humanresources/employees/search.md documentation index — /llms.txt

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 Req. Description
name string yes String to search by employee name
nodeId number no Limit 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 app

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 app

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
success boolean Always true on success
data.items array Array of found employees. Empty if there are no matches
data.items[].userId number Employee identifier
data.items[].name string Employee name
data.items[].workPosition string Employee position. Empty string if the position is not set
data.items[].avatar string URL of the employee's profile image
data.items[].url string Relative path to the employee's card in Bitrix24
data.items[].departments array Departments the employee belongs to
data.items[].departments[].id number Department identifier
data.items[].departments[].name string Department name
data.items[].teams array Teams 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
400 INVALID_PARAMS The name field is missing — error.validation carries a MISSING_NAME entry
403 SCOPE_DENIED The key lacks the humanresources scope
401 TOKEN_MISSING The 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