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

Search nodes

POST /v1/humanresources/nodes/search

Searches org structure nodes — departments or teams — by a substring of the name. Two body fields are required: type (the type of nodes to search) and name (the substring to search the node name by).

Unlike list nodes, which enumerates every node of the chosen type, search returns only nodes whose name contains the name substring. Search can additionally be restricted to a subtree via parentId and to a number of records via pagination.limit.

Request fields (body)

Field Type Req. Description
type string yes Type of nodes to search: DEPARTMENT (department) or TEAM (team)
name string yes Substring to search the node name by
parentId number no Parent node id — restricts the search to its subtree. A positive integer
pagination object no Pagination. Only pagination.limit is used
pagination.limit number no Maximum number of nodes in the response. Default 50, maximum 200
limit number no Alias for pagination.limit at the top level of the request body

The type and name fields go at the top level of the request body, not inside filter. The filter, order and select objects are not supported by this method.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Sales",
    "pagination": { "limit": 20 }
  }'

curl — OAuth app

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Sales",
    "pagination": { "limit": 20 }
  }'

JavaScript — personal key

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

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} departments`)

JavaScript — OAuth app

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

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of found nodes
data[].id number Node id
data[].name string Node name
data[].type string Node type: DEPARTMENT or TEAM
data[].structureId number Id of the structure the node belongs to
data[].parentId number | null Parent node id. null for the root node
data[].description string | null Node description. null when not set
data[].accessCode string Node access code (e.g. D185 for a department, SN23 for a team)
data[].userCount number Number of employees in the node
data[].colorName string | null Node color name. null when not set
data[].xmlId string | null External node id. null when not set
data[].createdAt string | null Creation date (ISO 8601). null for nodes created without a timestamp
data[].updatedAt string | null Last change date (ISO 8601). null when never changed
meta.total number Number of nodes in the response
meta.hasMore boolean Whether there are more records beyond the output

Search does not return the node membership — it comes only in the get node response.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 23,
      "name": "Sales department",
      "type": "DEPARTMENT",
      "structureId": 1,
      "parentId": 17,
      "description": "Direct sales",
      "accessCode": "SN23",
      "userCount": 2,
      "colorName": null,
      "xmlId": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

Error response example

400 — the name field is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "name is required — substring to search node names by"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS type missing (or not DEPARTMENT/TEAM), name missing, or parentId not a positive integer
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.

Notable details

type and name are required and go at the top level. Both fields go directly in the request body, without a filter wrapper. Omitting either returns 400 INVALID_PARAMS with a clear message. This differs from list nodes, where type is passed as a query-string parameter and there is no name filtering at all.

Sorting and field projection are not supported. The method does not accept order or select — nodes are returned in the order Bitrix24 provides, with all fields. To enumerate every node of a type, use list nodes.

See also