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. You can also narrow the search to a subtree with parentId and cap the number of records with 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. This method does not support the filter, order and select objects.

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, for example D185 or SN23. The prefix is not determined by the node type, and the numeric part may differ from id — take the value from the response
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 update date (ISO 8601). null if the node has never been updated
meta.total number Number of nodes in the response. Matches beyond pagination.limit are not counted
meta.hasMore boolean Always false — the search is not paginated. To check whether matches were cut off, repeat the request with a larger pagination.limit

Search does not return the node member roster — 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 is missing (or is not DEPARTMENT/TEAM), name is missing, or parentId is 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.

Known specifics

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 them, with all fields. To enumerate every node of a type, use list nodes.

See also