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

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

Terminal 
curl "https://vibecode.bitrix24.com/v1/humanresources/nodes/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
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.fields object Node field schema. The key is the field name in camelCase, the value is its descriptor
data.fields.<name>.type string Value type of the field: number, string or datetime
data.fields.<name>.readonly boolean true — the field is filled by the system and is refused on create and update with 400 READONLY_FIELD
data.fields.<name>.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.<name>.required boolean Present on fields that are required on creation
data.batch array Node operations available in a batch call: 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 on creation and accepted there 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 },
      "type": {
        "type": "string",
        "readonly": false,
        "createOnly": true,
        "required": true,
        "enum": [
          { "value": "DEPARTMENT", "label": "Department" },
          { "value": "TEAM", "label": "Team" }
        ]
      },
      "name": { "type": "string", "readonly": false, "required": true },
      "structureId": { "type": "number", "readonly": true },
      "parentId": { "type": "number", "readonly": false, "createOnly": true },
      "description": { "type": "string", "readonly": false },
      "accessCode": { "type": "string", "readonly": true },
      "userCount": { "type": "number", "readonly": true },
      "colorName": { "type": "string", "readonly": false },
      "xmlId": { "type": "string", "readonly": true },
      "createdAt": { "type": "datetime", "readonly": true },
      "updatedAt": { "type": "datetime", "readonly": true }
    },
    "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.

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