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
Parameter:entityTypeId (path) Typenumber Requiredyes DescriptionSmart process type identifier. Source: GET /v1/smart-processes — the entityTypeId field on each element of the data array
Parameter:id (path) Typenumber Requiredyes DescriptionNumeric 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionField object
Fielddata.id Typenumber DescriptionNumeric field identifier
Fielddata.entityId Typestring DescriptionInternal 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)
Fielddata.fieldName Typestring DescriptionSystem field name: UF_ + entityId + _<suffix>. For a regular smart process it is UF_CRM_<typeId>_<suffix>; for the smart invoice, UF_CRM_SMART_INVOICE_<suffix>
Fielddata.userTypeId Typestring DescriptionField type. List of allowed values — GET /v1/items/:entityTypeId/userfields/types
Fielddata.xmlId Typestring|null DescriptionExternal identifier for integrations. Set manually at creation
Fielddata.sort Typestring DescriptionSort order in the Bitrix24 interface
Fielddata.multiple Typestring DescriptionMultiple field: "Y" or "N"
Fielddata.mandatory Typestring DescriptionRequired on input: "Y" or "N"
Fielddata.showFilter Typestring DescriptionShow in filter: "N" — no, "I" — exact value, "E" — mask, "S" — range
Fielddata.showInList Typestring DescriptionShow in the record list: "Y" or "N"
Fielddata.editInList Typestring DescriptionAllow editing directly from the list: "Y" or "N"
Fielddata.isSearchable Typestring DescriptionWhether it participates in full-text search: "Y" or "N"
Fielddata.settings Typeobject DescriptionField settings specific to userTypeId. The set of keys depends on the type
Fielddata.languageId Typeobject DescriptionBitrix24 account languages: the key and value are the language code ({ "ru": "ru", … })
Fielddata.editFormLabel Typeobject DescriptionField label in the edit form. An object keyed by Bitrix24 account language: the value for the relevant locale, the rest are ""
Fielddata.listColumnLabel Typeobject DescriptionColumn header in the record list. An object keyed by language; if not set — values are null
Fielddata.listFilterLabel Typeobject DescriptionField label in the filter. An object keyed by language; if not set — values are null
Fielddata.errorMessage Typeobject DescriptionValidation error message. An object keyed by language; if not set — values are null
Fielddata.helpMessage Typeobject DescriptionHint below the field in the form. An object keyed by language; if not set — values are null
Fielddata.enum Typearray DescriptionOnly 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
HTTP400 CodeINVALID_ENTITY_TYPE_ID Description:entityTypeId is not a positive integer
HTTP400 CodeINVALID_PARAMS Description:id is not a positive integer or exceeds 9007199254740991. The value must contain digits only, with no leading zero, sign, fractional part, exponent or spaces. Message: id must be a positive integer. No request is sent to Bitrix24
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key has no userfieldconfig scope — reissue the key with this scope
HTTP403 CodeSCOPE_DENIED DescriptionThe API key has no crm scope
HTTP404 CodeSMART_PROCESS_NOT_FOUND DescriptionA smart process with the given entityTypeId was not found on the portal
HTTP404 CodeNOT_FOUND DescriptionThe smart process in the path has no field with the given id: the field was deleted or belongs to another entity
HTTP422 CodeBITRIX_ERROR DescriptionThe field was deleted between the check and the read — Bitrix24 responds "You cannot view the user field settings"
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The field is looked up only in the smart process from the path. Field ids are numbered across all entities of the Bitrix24 account, so before reading, the platform checks that the smart process :entityTypeId has a field with this id. A field of another entity and a deleted field return the same response, 404 NOT_FOUND. 404 SMART_PROCESS_NOT_FOUND applies to a non-existent entityTypeId.

See also