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

List entity fields

GET /v1/userfields/:entity

Returns the list of user fields of a CRM entity. Supports filtering by field type and by name.

Parameters

Parameter Type Required Description
:entity (path) string yes Entity: deals, leads, contacts, companies, quotes, requisites
userTypeId (query) string no Filter by field type. The list of allowed values — GET /v1/userfields/:entity/types. Example: ?userTypeId=string
fieldName (query) string no Filter by field name in the UF_CRM_* format. Example: ?fieldName=UF_CRM_PROJECT_CODE

The result is ordered by the sort field ascending. A sort parameter is not accepted.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/userfields/deals?userTypeId=string" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/userfields/deals?userTypeId=string" \
  -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/userfields/deals?userTypeId=string',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data, meta } = await res.json()
console.log(`Fields of type string: ${meta.total}`)

JavaScript — OAuth application

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of entity fields. An item's field set matches the field card EXCEPT the localized labels editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage — those are returned only by the card GET /:entity/:id (see "Known specifics")
meta.total number Total number of fields matching the filter

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 6737,
      "entityId": "CRM_DEAL",
      "fieldName": "UF_CRM_66976FE34823A",
      "userTypeId": "string",
      "xmlId": null,
      "sort": "100",
      "multiple": "N",
      "mandatory": "N",
      "showFilter": "E",
      "showInList": "Y",
      "editInList": "Y",
      "isSearchable": "N",
      "settings": {
        "SIZE": 20,
        "ROWS": 1,
        "REGEXP": "",
        "MIN_LENGTH": 0,
        "MAX_LENGTH": 0,
        "DEFAULT_VALUE": ""
      }
    },
    {
      "id": 6739,
      "entityId": "CRM_DEAL",
      "fieldName": "UF_CRM_66976FE35F480",
      "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": ""
      }
    }
  ],
  "meta": {
    "total": 7
  }
}

Error response example

400 — unknown entity:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_ENTITY",
    "message": "Unsupported entity \"foobar\". Supported: deals, leads, contacts, companies, quotes, requisites"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_ENTITY :entity is not in the list of supported entities
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The API key has no configured tokens
403 SCOPE_DENIED The API key does not have the crm scope

Full list of common API errors — Errors.

Known specifics

Localized labels arrive only in the card. The list does NOT return the field's localized labels — editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage. Bitrix24 returns them from crm.<entity>.userfield.list only when a LANG filter is set, which this endpoint does not pass. For localized labels use the field card (GET /v1/userfields/:entity/:id) — it returns them as objects keyed by Bitrix24 account languages. Every other item field is identical to the card.

The settings object. The structure of the settings field depends on userTypeId. For a string it is SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE. For other types — a different set of keys. When a field type has no configurable parameters, Bitrix24 may return settings as an empty array [] instead of {} (a PHP empty-array serialization quirk) — treat such a value as "no settings".

No pagination. The endpoint returns all entity fields without splitting into pages. meta.total reflects the resulting number of fields in the response.

See also