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 Required Description
Fieldtype Typestring Requiredyes DescriptionType of nodes to search: DEPARTMENT (department) or TEAM (team)
Fieldname Typestring Requiredyes DescriptionSubstring to search the node name by
FieldparentId Typenumber Requiredno DescriptionParent node ID — restricts the search to its subtree. A positive integer
Fieldpagination Typeobject Requiredno DescriptionPagination. Only pagination.limit is used
Fieldpagination.limit Typenumber Requiredno DescriptionMaximum number of nodes in the response. Default 50, maximum 200
Fieldlimit Typenumber Requiredno DescriptionAlias 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 application

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 application

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of found nodes
Fielddata[].id Typenumber DescriptionNode ID
Fielddata[].name Typestring DescriptionNode name
Fielddata[].type Typestring DescriptionNode type: DEPARTMENT or TEAM
Fielddata[].structureId Typenumber DescriptionID of the structure the node belongs to
Fielddata[].parentId Typenumber | null DescriptionParent node ID. null for the root node
Fielddata[].description Typestring | null DescriptionNode description. null when not set
Fielddata[].accessCode Typestring DescriptionNode 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
Fielddata[].userCount Typenumber DescriptionNumber of employees in the node
Fielddata[].colorName Typestring | null DescriptionNode color name. null when not set
Fielddata[].xmlId Typestring | null DescriptionExternal node ID. null when not set
Fielddata[].createdAt Typestring | null DescriptionCreation date (ISO 8601). null for nodes created without a timestamp
Fielddata[].updatedAt Typestring | null DescriptionLast update date (ISO 8601). null if the node has never been updated
Fieldmeta.total Typenumber DescriptionNumber of nodes in the response. Matches beyond pagination.limit are not counted
Fieldmeta.hasMore Typeboolean DescriptionAlways 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
HTTP400 CodeINVALID_PARAMS Descriptiontype is missing (or is not DEPARTMENT/TEAM), name is missing, or parentId is not a positive integer
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

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