## Org structure node fields `GET /v1/humanresources/nodes/fields` Returns the field schema of an org structure node: value type, read-only flag, whether the field is accepted on creation only, whether it is required, and the allowed values. ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/humanresources/nodes/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/humanresources/nodes/fields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { success, data } = await res.json() console.log('Fields:', Object.keys(data.fields).length) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/humanresources/nodes/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { success, data } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | Field schema and the list of operations available in a batch call | | `data.fields` | object | Node field schema. The key is the field name in camelCase, the value is its descriptor | | `data.fields..type` | string | Value type of the field: `number`, `string` or `datetime` | | `data.fields..label` | string | Human-readable field name | | `data.fields..description` | string | Field description: purpose and write rules | | `data.fields..readonly` | boolean | `true` — the field is filled by the system and is refused on create and update with `400 READONLY_FIELD` | | `data.fields..createOnly` | boolean | Present on fields accepted only when a node is created. In an update request such a field is refused with `400 READONLY_FIELD` | | `data.fields..required` | boolean | Present on fields that are required on creation | | `data.batch` | array | Node operations available in a [batch call](/docs/batch): `create`, `update` | A descriptor also carries `enum` when the field has a fixed set of values: every element holds `value` to send in the request and the English caption `label`. The schema describes twelve fields: | Field | Type | RO | Description | |------|-----|:--:|---------| | `id` | number | yes | Node identifier | | `type` | string | | Node type. Required and accepted on creation only. The allowed values are listed in `enum`: `DEPARTMENT` — a department, `TEAM` — a team | | `name` | string | | Node name. Required on creation | | `structureId` | number | yes | Identifier of the structure the node belongs to | | `parentId` | number | | Identifier of the parent node. Accepted on creation only. Identifier list: `GET /v1/humanresources/nodes?type=DEPARTMENT` | | `description` | string | | Node description | | `accessCode` | string | yes | Access code of the node | | `userCount` | number | yes | Number of employees in the node | | `colorName` | string | | Name of the node color | | `xmlId` | string | yes | External identifier of the node | | `createdAt` | datetime | yes | Node creation date | | `updatedAt` | datetime | yes | Date the node was last changed | ## Response example ```json { "success": true, "data": { "fields": { "id": { "type": "number", "readonly": true, "label": "Node ID", "description": "Node identifier." }, "type": { "type": "string", "readonly": false, "createOnly": true, "required": true, "label": "Node type", "description": "Node type. Required on creation and accepted there only.", "enum": [ { "value": "DEPARTMENT", "label": "Department" }, { "value": "TEAM", "label": "Team" } ] }, "name": { "type": "string", "readonly": false, "required": true, "label": "Node name", "description": "Node name. Required on creation." }, "structureId": { "type": "number", "readonly": true, "label": "Structure ID", "description": "Identifier of the structure the node belongs to." }, "parentId": { "type": "number", "readonly": false, "createOnly": true, "label": "Parent node ID", "description": "Identifier of the parent node. Accepted on creation only. Identifier list: GET /v1/humanresources/nodes?type=DEPARTMENT." }, "description": { "type": "string", "readonly": false, "label": "Description", "description": "Node description." }, "accessCode": { "type": "string", "readonly": true, "label": "Access code", "description": "Access code of the node." }, "userCount": { "type": "number", "readonly": true, "label": "Employee count", "description": "Number of employees in the node." }, "colorName": { "type": "string", "readonly": false, "label": "Color name", "description": "Name of the node color." }, "xmlId": { "type": "string", "readonly": true, "label": "External ID", "description": "External identifier of the node." }, "createdAt": { "type": "datetime", "readonly": true, "label": "Created at", "description": "Node creation date." }, "updatedAt": { "type": "datetime", "readonly": true, "label": "Updated at", "description": "Date the node was last changed." } }, "batch": ["create", "update"] } } ``` ## Error response example 403 — scope missing: ```json { "success": false, "error": { "code": "SCOPE_DENIED", "message": "This endpoint requires 'humanresources' scope" } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 403 | `SCOPE_DENIED` | The key lacks the `humanresources` scope | | 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not sent | | 401 | `TOKEN_MISSING` | The API key has no configured Bitrix24 tokens | Full list of general API errors — [Errors](/docs/errors). ## Known specifics **`createOnly` is not the same as `readonly`.** Both refusals arrive with the same code `400 READONLY_FIELD`, so this schema is the only way to tell "the field cannot be changed after creation" from "the field cannot be set at all". **The field set does not depend on the Bitrix24 account.** The response is assembled from the entity declaration on the Vibecode platform side and is never requested from the account. So the set of fields, their types and the `enum` values are identical on every account and do not change when Bitrix24 is unreachable. ## See also - [List nodes](/docs/humanresources/nodes/list) - [Get node](/docs/humanresources/nodes/get) - [Create node](/docs/humanresources/nodes/create) - [Update node](/docs/humanresources/nodes/update) - [Org structure nodes](/docs/humanresources/nodes)