For AI agents: markdown of this page — /docs-content-en/entities/crm-forms/entity-fields.md documentation index — /llms.txt

List entity fields

GET /v1/crm-forms/entity-fields

Returns the fields of leads, contacts, companies, deals and other CRM entities that can be added to a CRM form. Call it before creating or updating a form to look up field names.

Parameters

Parameter Type Required Description
ParameterentityName (query) Typestring Requiredyes DescriptionCRM entity name, for example LEAD, CONTACT, COMPANY, DEAL, DYNAMIC_177. For the list, see data.entitySchemes[].entityNames in Builder configuration.
To request several entities, pass up to 10 names in one of these ways: comma-separated ?entityName=LEAD,CONTACT, repeated ?entityName=LEAD&entityName=CONTACT or ?entityName[]=LEAD&entityName[]=CONTACT

The endpoint accepts no other query parameters.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm-forms/entity-fields?entityName=LEAD" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/crm-forms/entity-fields?entityName=LEAD" \
  -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/crm-forms/entity-fields?entityName=LEAD', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log(data.map(field => `${field.name} — ${field.label}`))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/entity-fields?entityName=LEAD', {
  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 Typearray DescriptionFields of all requested entities in one array. No pagination
Fielddata[].name Typestring DescriptionField name in the form: the entity name plus the field code, for example LEAD_NAME. Pass this value in fields[].name when creating a form
Fielddata[].label Typestring DescriptionField label
Fielddata[].type Typestring DescriptionField type: string, text, list, date, datetime, double, file, typed_string, crm_entity, resourcebooking. The typed_string type is used by communication fields: phone, email, website, messenger
Fielddata[].required Typeboolean DescriptionWhether the field is required
Fielddata[].multiple Typeboolean DescriptionWhether the field accepts multiple values
Fielddata[].entityName Typestring DescriptionEntity the field belongs to, for example LEAD
Fielddata[].entityLabel Typestring DescriptionEntity label
Fielddata[].items Typearray DescriptionValue options of a list field. An empty array for fields of other types
Fielddata[].items[].id Typestring DescriptionOption ID, for example WEB in the LEAD_SOURCE_ID field
Fielddata[].items[].label Typestring DescriptionOption label

Response example

The example shows four fields from the lead response. Option IDs depend on the Bitrix24 account; labels in this example are illustrative:

JSON 
{
  "success": true,
  "data": [
    {
      "name": "LEAD_TITLE",
      "label": "Lead name",
      "type": "string",
      "required": false,
      "multiple": false,
      "entityName": "LEAD",
      "entityLabel": "Lead",
      "items": []
    },
    {
      "name": "LEAD_HONORIFIC",
      "label": "Salutation",
      "type": "list",
      "required": false,
      "multiple": false,
      "entityName": "LEAD",
      "entityLabel": "Lead",
      "items": [
        {
          "id": "HNR_RU_1",
          "label": "Mr."
        },
        {
          "id": "HNR_RU_2",
          "label": "Mrs."
        }
      ]
    },
    {
      "name": "LEAD_NAME",
      "label": "First name",
      "type": "string",
      "required": false,
      "multiple": false,
      "entityName": "LEAD",
      "entityLabel": "Lead",
      "items": []
    },
    {
      "name": "LEAD_PHONE",
      "label": "Phone",
      "type": "typed_string",
      "required": false,
      "multiple": true,
      "entityName": "LEAD",
      "entityLabel": "Lead",
      "items": []
    }
  ]
}

Error response example

400 — entityName is not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "entityName is required"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionentityName is missing
HTTP400 CodeINVALID_PARAMS DescriptionMore than 10 names, an empty name, or an unknown query parameter
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe Bitrix24 user lacks permission to access forms
HTTP403 CodeBITRIX_INSUFFICIENT_SCOPE DescriptionThe Bitrix24 token lacks the required scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 did not find a requested entity or field descriptor. The original code is in error.b24Code
HTTP409 CodeCRM_FORM_REST_NOT_ENABLED DescriptionThe CRM form REST methods are unavailable on this Bitrix24 account. This does not mean that an individual form is missing
HTTP400–599 CodeCRM_FORM_* DescriptionRejection under form rules. The code and HTTP status are preserved. The original code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionAnother Bitrix24 rejection. The reason is in error.message. The original code is in error.b24Code
HTTP429 CodeRATE_LIMITED DescriptionRequest rate exceeded. Follow the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an unexpected response shape
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable: a server error or a dropped connection
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time. The read can be retried
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured Bitrix24 credentials
HTTP403 CodeSCOPE_DENIED DescriptionThe Vibecode API key lacks the crm scope

Full list of common API errors — Errors.

See also