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

Node members

Managing the membership of an organizational structure node: adding and removing members, moving them between nodes, and fully replacing the list. Each member is assigned a role within the node.

Bitrix24 API: humanresources.node.member.* Scope: humanresources

Member roles

The set of roles depends on the node type. For a department:

  • MEMBER_HEAD — head
  • MEMBER_DEPUTY_HEAD — deputy head
  • MEMBER_EMPLOYEE — employee

For a team:

  • MEMBER_TEAM_HEAD — team head
  • MEMBER_TEAM_DEPUTY_HEAD — team deputy head
  • MEMBER_TEAM_EMPLOYEE — team member

Add members

POST /v1/humanresources/nodes/:id/members/add

Adds one or more employees to an organizational structure node with the specified role. A single call can add several members at once — all of them receive the same role.

Parameters

Parameter Type Required Description
id (path) number yes Identifier of the node members are added to. List of identifiers: GET /v1/humanresources/nodes?type=DEPARTMENT

Request body fields

Field Type Required Description
userIds array yes Employee identifiers. Search: POST /v1/humanresources/employees/search
role string yes Role assigned to all added employees. The set of roles depends on the node type. Available roles — Node members

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes/23/members/add" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userIds": [42, 108], "role": "MEMBER_EMPLOYEE" }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes/23/members/add" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "userIds": [42, 108], "role": "MEMBER_EMPLOYEE" }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes/23/members/add', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [42, 108], role: 'MEMBER_EMPLOYEE' }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes/23/members/add', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userIds: [42, 108], role: 'MEMBER_EMPLOYEE' }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data.success boolean Confirmation that the members were added

Response example

JSON 
{
  "success": true,
  "data": {
    "success": true
  }
}

Error response example

400 — role not provided:

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

Errors

HTTP Code Description
400 INVALID_PARAMS The role parameter was not provided (validation[].field = MISSING_ROLE)
400 INVALID_PARAMS Invalid role value for the node type. The message lists the allowed roles (validation[].field = INVALID_ROLE)
400 INVALID_PARAMS Non-numeric id in the path — id must be a positive integer
404 NOT_FOUND Unknown verb in the path after members/. The message lists the allowed ones: move, remove, add, set
403 SCOPE_DENIED The key is missing the humanresources scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

The list of roles arrives in the error message. When the role is invalid for the node type (validation[].field = INVALID_ROLE), the message lists the allowed values — you can pick a correct role from this list without consulting the reference.

See also