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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionField schema and the list of operations available in a batch call
Fielddata.fields Typeobject DescriptionNode field schema. The key is the field name in camelCase, the value is its descriptor
Fielddata.fields.<name>.type Typestring DescriptionValue type of the field: number, string or datetime
Fielddata.fields.<name>.label Typestring DescriptionHuman-readable field name
Fielddata.fields.<name>.description Typestring DescriptionField description: purpose and write rules
Fielddata.fields.<name>.readonly Typeboolean Descriptiontrue — the field is filled by the system and is refused on create and update with 400 READONLY_FIELD
Fielddata.fields.<name>.createOnly Typeboolean DescriptionPresent on fields accepted only when a node is created. In an update request such a field is refused with 400 READONLY_FIELD
Fielddata.fields.<name>.required Typeboolean DescriptionPresent on fields that are required on creation
Fielddata.batch Typearray DescriptionNode 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
Fieldid Typenumber ROyes DescriptionNode identifier
Fieldtype Typestring RO DescriptionNode type. Required and accepted on creation only. The allowed values are listed in enum: DEPARTMENT — a department, TEAM — a team
Fieldname Typestring RO DescriptionNode name. Required on creation
FieldstructureId Typenumber ROyes DescriptionIdentifier of the structure the node belongs to
FieldparentId Typenumber RO DescriptionIdentifier of the parent node. Accepted on creation only. Identifier list: GET /v1/humanresources/nodes?type=DEPARTMENT
Fielddescription Typestring RO DescriptionNode description
FieldaccessCode Typestring ROyes DescriptionAccess code of the node
FielduserCount Typenumber ROyes DescriptionNumber of employees in the node
FieldcolorName Typestring RO DescriptionName of the node color
FieldxmlId Typestring ROyes DescriptionExternal identifier of the node
FieldcreatedAt Typedatetime ROyes DescriptionNode creation date
FieldupdatedAt Typedatetime ROyes DescriptionDate 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
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the humanresources scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not sent
HTTP401 CodeTOKEN_MISSING DescriptionThe 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