Get field

GET /v1/userfields/:entity/:id

Returns the full description of a single user field of a CRM entity by its numeric identifier.

Parameters

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/userfields/deals/7115" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/userfields/deals/7115" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch(
  'https://vibecode.bitrix24.com/v1/userfields/deals/7115',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(data.fieldName, data.userTypeId)

JavaScript — OAuth application

const res = await fetch(
  'https://vibecode.bitrix24.com/v1/userfields/deals/7115',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data } = await res.json()

Response fields

Response example

The language objects (editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage) arrive for all Bitrix24 account languages. Three keys are kept in the example for brevity.

{
  "success": true,
  "data": {
    "id": 7115,
    "entityId": "CRM_DEAL",
    "fieldName": "UF_CRM_VIBE_DOC_1779951810",
    "userTypeId": "string",
    "xmlId": null,
    "sort": "100",
    "multiple": "N",
    "mandatory": "N",
    "showFilter": "N",
    "showInList": "Y",
    "editInList": "Y",
    "isSearchable": "N",
    "settings": {
      "SIZE": 20,
      "ROWS": 1,
      "REGEXP": "",
      "MIN_LENGTH": 0,
      "MAX_LENGTH": 0,
      "DEFAULT_VALUE": ""
    },
    "editFormLabel": {
      "en": "Documentation field",
      "de": "Documentation field",
      "fr": "Documentation field"
    },
    "listColumnLabel": {
      "en": "Documentation field",
      "de": "Documentation field",
      "fr": "Documentation field"
    },
    "listFilterLabel": {
      "en": "Documentation field",
      "de": "Documentation field",
      "fr": "Documentation field"
    },
    "errorMessage": {
      "en": "Documentation field",
      "de": "Documentation field",
      "fr": "Documentation field"
    },
    "helpMessage": {
      "en": "Documentation field",
      "de": "Documentation field",
      "fr": "Documentation field"
    }
  }
}

Error response example

404 — the field does not exist:

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "The entity with ID '9999999' is not found."
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Language objects. The fields editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage arrive as objects with values per Bitrix24 account language (ru, en, ua, de, fr, and others). The value is set when the field is created or updated via the label parameter. If only a string is passed ("label": "My title"), Bitrix24 automatically propagates it to all available languages.

The settings field. The structure of the settings object depends on the value of userTypeId. Key sets for common types:

• string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE
• enumeration — DISPLAY, LIST_HEIGHT, CAPTION_NO_VALUE, SHOW_NO_VALUE
• datetime — DEFAULT_VALUE, USE_SECOND, USE_TIMEZONE
• crm — LEAD, CONTACT, COMPANY, DEAL set to "Y" or "N". A field whose smart process link was set outside this API carries the DYNAMIC_<entityTypeId> key and may lack the other keys

Other types have their own set of keys.

The type of the nested settings.DEFAULT_VALUE key also depends on userTypeId: an empty string "" for string and money, the number 0 for boolean, an object { "TYPE": ..., "VALUE": ... } for date and datetime, an empty array [] for employee. The composition and types of nested settings keys are not fixed — rely on the specific userTypeId rather than on a single set.

When a field type has no configurable parameters, Bitrix24 may return the settings field itself as an empty array [] instead of {} (a PHP empty associative-array serialization quirk). Treat an empty array as "no settings" — do not rely on settings always being an object.

See also

• List entity fields
• Field type catalog
• Create field
• Update field
• CRM entity fields
• User fields