For AI agents: markdown of this page — /docs-content-en/userfields/smart-processes/get.md documentation index — /llms.txt

Get field

GET /v1/items/:entityTypeId/userfields/:id

Returns the full description of a single smart process user field by its numeric identifier.

Parameters

Parameter Type Required Description
:entityTypeId (path) number yes Smart process type identifier. Source: GET /v1/smart-processes — the entityTypeId field on each element of the data array
:id (path) number yes Numeric field identifier (from the response of GET /v1/items/:entityTypeId/userfields or POST /v1/items/:entityTypeId/userfields)

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/items/174/userfields/8210" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/items/174/userfields/8210" \
  -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/items/174/userfields/8210',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(data.fieldName, data.userTypeId)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/items/174/userfields/8210',
  {
    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 object
data.id number Numeric field identifier
data.entityId string Internal identifier of the form CRM_<typeId>, where typeId is the internal sequential identifier of the smart process (does not match the entityTypeId from the path)
data.fieldName string System field name in the UF_CRM_<typeId>_<suffix> format
data.userTypeId string Field type. List of allowed values — GET /v1/items/:entityTypeId/userfields/types
data.xmlId string|null External identifier for integrations. Set manually at creation
data.sort string Sort order in the Bitrix24 interface
data.multiple string Multiple field: "Y" or "N"
data.mandatory string Required on input: "Y" or "N"
data.showFilter string Show in filter: "N" — no, "I" — exact value, "E" — mask, "S" — range
data.showInList string Show in the record list: "Y" or "N"
data.editInList string Allow editing directly from the list: "Y" or "N"
data.isSearchable string Whether it participates in full-text search: "Y" or "N"
data.settings object Field settings specific to userTypeId. The set of keys depends on the type
data.languageId object Bitrix24 account languages: the key and value are the language code ({ "ru": "ru", … })
data.editFormLabel object Field label in the edit form. An object keyed by Bitrix24 account language: the value for the relevant locale, the rest are ""
data.listColumnLabel object Column header in the record list. An object keyed by language; if not set — values are null
data.listFilterLabel object Field label in the filter. An object keyed by language; if not set — values are null
data.errorMessage object Validation error message. An object keyed by language; if not set — values are null
data.helpMessage object Hint below the field in the form. An object keyed by language; if not set — values are null
data.enum array Only for the enumeration type: value options. Each element contains id, userFieldId, value, def, sort, xmlId

Response example

The language objects (languageId, editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage) are returned for all Bitrix24 account languages. In the example only en is kept, with … instead of the rest.

JSON 
{
  "success": true,
  "data": {
    "id": 3351,
    "entityId": "CRM_3",
    "fieldName": "UF_CRM_3_1628508893",
    "userTypeId": "string",
    "xmlId": null,
    "sort": "100",
    "multiple": "N",
    "mandatory": "N",
    "showFilter": "E",
    "showInList": "Y",
    "editInList": "Y",
    "isSearchable": "Y",
    "settings": {
      "SIZE": 20,
      "ROWS": 1,
      "REGEXP": "",
      "MIN_LENGTH": 0,
      "MAX_LENGTH": 0,
      "DEFAULT_VALUE": ""
    },
    "languageId": { "en": "en", "…": "…" },
    "editFormLabel": { "en": "String1", "…": "" },
    "listColumnLabel": { "en": null, "…": null },
    "listFilterLabel": { "en": null, "…": null },
    "errorMessage": { "en": null, "…": null },
    "helpMessage": { "en": null, "…": null }
  }
}

For an enumeration-type field, the response additionally includes an enum array with the options:

JSON 
"enum": [
  { "id": "1347", "userFieldId": "3929", "value": "1", "def": "N", "sort": "100", "xmlId": "a84972a4857b64f963b165785b3c20d0" }
]

Error response example

403 — the key has no userfieldconfig scope:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "The request requires higher privileges than provided by the webhook token"
  }
}

Errors

HTTP Code Description
400 INVALID_ENTITY_TYPE_ID :entityTypeId is not a positive integer
403 BITRIX_ACCESS_DENIED The key has no userfieldconfig scope — reissue the key with this scope
403 SCOPE_DENIED The API key has no crm scope
404 SMART_PROCESS_NOT_FOUND A smart process with the given entityTypeId was not found on the portal
422 BITRIX_ERROR The field with the given id does not exist (or it was deleted) — Bitrix24 responds "You cannot view the user field settings"
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

A non-existent field yields 422, not 404. If the field with the given id does not exist (for example, it was deleted), Bitrix24 responds with 422 BITRIX_ERROR and the message "You cannot view the user field settings" — no separate 404 for the field is returned. 404 SMART_PROCESS_NOT_FOUND applies only to a non-existent entityTypeId.

See also