## Create node

`POST /v1/humanresources/nodes`

Creates an org structure node of a Bitrix24 account — a department or a team in the org structure tree. The node type is set by the `type` field; fields are passed flat at the JSON root without a `fields` wrapper.

## Request fields (body)

| Field | Type | Req. | Description |
|------|-----|:-----:|---------|
| `type` | string | yes | Node type: `DEPARTMENT` (department) or `TEAM` (team) |
| `name` | string | yes | Node name |
| `parentId` | number | no | Parent node identifier in the tree. List: `GET /v1/humanresources/nodes` |
| `description` | string | no | Node description |
| `colorName` | string | no | Node color code, for example `blue` or `AZURE` |
| `userIds` | object | no | Members by role right at creation: `{ "MEMBER_HEAD": [1], "MEMBER_EMPLOYEE": [2, 3] }`. The key is the role, the value is an array of identifiers (not a flat array, unlike [adding members](/docs/humanresources/members/add)) |
| `moveUsersToNode` | boolean | no | Move the employees in `userIds` to the new node, removing them from their previous ones. Defaults to `false` |
| `createChat` | boolean | no | Create a group chat for the node. Defaults to `false` |
| `bindingChatIds` | number[] | no | Identifiers of existing chats to bind to the node |
| `createChannel` | boolean | no | Create a channel for the node. Defaults to `false` |
| `bindingChannelIds` | number[] | no | Identifiers of existing channels to bind |
| `createCollab` | boolean | no | Create a collab space for the node. Defaults to `false` |
| `bindingCollabIds` | number[] | no | Identifiers of existing collab spaces to bind |
| `id` | number | RO | Node identifier, assigned at creation |
| `structureId` | number | RO | Identifier of the structure the node belongs to |
| `accessCode` | string | RO | Node access code, generated by the system (for example, `SN39`) |
| `userCount` | number | RO | Number of employees in the node |
| `xmlId` | string | RO | External identifier of the node |
| `createdAt` | datetime | RO | Creation date |
| `updatedAt` | datetime | RO | Last update date |

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Sales department",
    "parentId": 1,
    "description": "Active sales managers",
    "colorName": "blue"
  }'
```

### curl — OAuth app

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/humanresources/nodes" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Sales department",
    "parentId": 1,
    "description": "Active sales managers",
    "colorName": "blue"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'DEPARTMENT',
    name: 'Sales department',
    parentId: 1,
    description: 'Active sales managers',
    colorName: 'blue',
  }),
})

const { success, data } = await res.json()
console.log('Node ID:', data.id)
```

### JavaScript — OAuth app

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes', {
  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 department',
    parentId: 1,
    description: 'Active sales managers',
    colorName: 'blue',
  }),
})

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

## Response fields

Returns the full record of the created node.

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Identifier of the created node |
| `name` | string | Node name |
| `type` | string | Node type: `DEPARTMENT` or `TEAM` |
| `structureId` | number | Identifier of the structure the node belongs to |
| `parentId` | number | Parent node identifier |
| `description` | string | Node description |
| `accessCode` | string | Node access code generated by the system |
| `userCount` | number | Number of employees in the node. For a new node — `0` |
| `colorName` | string | Node color |
| `xmlId` | string | External identifier of the node |
| `createdAt` | datetime | Creation date |
| `updatedAt` | datetime | Last update date |
| `members` | array | List of node members. For a new node — an empty array |

## Response example

```json
{
  "success": true,
  "data": {
    "id": 39,
    "name": "Sales department",
    "type": "DEPARTMENT",
    "structureId": 1,
    "parentId": 1,
    "description": "Active sales managers",
    "accessCode": "SN39",
    "userCount": 0,
    "colorName": "blue",
    "xmlId": null,
    "createdAt": "2026-06-03T13:06:45.000Z",
    "updatedAt": "2026-06-03T13:06:45.000Z",
    "members": []
  }
}
```

## Error response example

400 — required field `name` not provided:

```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` | A required field was not provided. In `error.validation` — the marker `MISSING_NAME` (`name` missing) or `MISSING_TYPE` (`type` missing) |
| 403 | `SCOPE_DENIED` | The key lacks the `humanresources` scope |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Initial node setup in a single request.** Besides the base fields, at creation you can immediately set the member roster by role (`userIds`) and communication tools: create a chat, channel or collab space (`createChat` / `createChannel` / `createCollab`) or bind existing ones by identifiers (`bindingChatIds` / `bindingChannelIds` / `bindingCollabIds`). These fields are optional — without them an empty node is created.

## See also

- [List nodes](/docs/humanresources/nodes/list)
- [Get node](/docs/humanresources/nodes/get)
- [Update node](/docs/humanresources/nodes/update)
- [Search nodes](/docs/humanresources/nodes/search)
- [Org structure nodes](/docs/humanresources/nodes)