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

Company fields

GET /v1/companies/fields

Returns the full list of available fields, including user fields (ufCrm*).

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/companies/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/companies/fields" \
  -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/companies/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/companies/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

The label and description field captions are returned in English, while the ones the platform takes straight from the Bitrix24 account come in the account language. Request headers do not switch the language.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe company field schema and the operations available for companies. Its keys are in the rows below
Fielddata.fields Typeobject DescriptionThe company field schema: field name → an object with type, readonly and label. Some fields also carry description and extra attributes such as nullable, multiple and items. The standard fields are listed below, and the ufCrm* user fields of this Bitrix24 account are added to them
Fielddata.relations Typeobject DescriptionThe contact relation covers all contacts linked to the company and the operations on them. See Company contacts
Fielddata.activities Typeobject DescriptionCompany activities: the list and create operations and the call, meeting, email and task activity types. See Activities of a CRM record and Create an activity for a CRM record
Fielddata.aggregatable Typearray DescriptionStandard fields allowed in the aggregation groupBy: typeId, industry, revenue, assignedById, sourceId
Fielddata.batch Typearray DescriptionCompany write operations available in batch calls: create, update, delete
Fielddata.import Typeobject DescriptionMethod, path and maximum batch size for importing records
Fielddata.include Typearray DescriptionThe names the include parameter accepts: contact. See Related data

Standard company fields

Field Type RO Description
Fieldid Typenumber ROyes DescriptionCompany ID
Fieldtitle Typestring RO DescriptionName
FieldtypeId Typestring RO DescriptionCompany type: CUSTOMER, SUPPLIER, COMPETITOR. Values list: GET /v1/statuses?filter[entityId]=COMPANY_TYPE
Fieldindustry Typestring RO DescriptionIndustry. List: GET /v1/statuses?filter[entityId]=INDUSTRY
Fieldrevenue Typenumber RO DescriptionAnnual revenue
FieldcurrencyId Typestring RO DescriptionCurrency. List: GET /v1/currencies
Fieldphone Typemultifield RO DescriptionPhone. On input (POST/PATCH) accepts string | string[] | object[]. On output, phone is a string with the primary value. Per-type values are in phoneWork/phoneMobile, and the full list with types is in the fm[] array (format { id, typeId, valueType, value }). Important: PATCH only adds new records — existing phone entries are not removed. See Update company. Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]. An object with an id field is not accepted by any write operation — 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written. The same applies to a row with id inside the raw fm[] array. An object keyed by row ids ({"11": {…}}) is not accepted either — same code. An object without value — empty or with keys such as n0, 0 or 011 — and a number or true/false, on their own or as an array item, are refused with 400 INVALID_MULTIFIELD_SHAPE.
Fieldemail Typemultifield RO DescriptionEmail. On input accepts string | string[] | object[]. On output, email is a string with the primary value. Per-type values are in emailWork/emailHome/emailMailing, and the full list is in the fm[] array. Important: PATCH only adds new records — existing email entries are not removed. Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]. An object with an id field is not accepted by any write operation — 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written. The same applies to a row with id inside the raw fm[] array. An object keyed by row ids ({"11": {…}}) is not accepted either — same code. An object without value — empty or with keys such as n0, 0 or 011 — and a number or true/false, on their own or as an array item, are refused with 400 INVALID_MULTIFIELD_SHAPE.
Fieldweb Typemultifield RO DescriptionWebsite. On input accepts string | string[] | object[]. On output, web is a string with the primary value. Per-type values are in webWork, and the full list is in the fm[] array. Important: PATCH only adds new records — existing web entries are not removed. Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]. An object with an id field is not accepted by any write operation — 400 MULTIFIELD_ID_NOT_SUPPORTED, and nothing is written. The same applies to a row with id inside the raw fm[] array. An object keyed by row ids ({"11": {…}}) is not accepted either — same code. An object without value — empty or with keys such as n0, 0 or 011 — and a number or true/false, on their own or as an array item, are refused with 400 INVALID_MULTIFIELD_SHAPE.
FieldhasPhone Typeboolean ROyes DescriptionWhether a phone is set
FieldhasEmail Typeboolean ROyes DescriptionWhether an email is set
FieldhasImol Typeboolean ROyes DescriptionWhether there is an Open Channel contact
Fieldcomments Typestring RO DescriptionComment
FieldsourceId Typestring RO DescriptionSource. List: GET /v1/statuses?filter[entityId]=SOURCE
FieldsourceDescription Typestring RO DescriptionSource description
FieldassignedById Typenumber RO DescriptionResponsible person. List: GET /v1/users
FieldcreatedBy Typenumber ROyes DescriptionCreator. Lookup: GET /v1/users
FieldupdatedBy Typenumber ROyes DescriptionModified by. Lookup: GET /v1/users
FieldcreatedTime Typedatetime ROyes DescriptionCreation date
FieldupdatedTime Typedatetime ROyes DescriptionModification date
Fieldopened Typeboolean RO DescriptionAvailable to everyone
FieldleadId Typenumber RO DescriptionID of the source lead
FieldentityTypeId Typenumber ROyes DescriptionCRM entity type ID. For a company the value is always 4
FieldemailWork Typestring | null ROyes DescriptionWork e-mail from the email multifield. Written through email
FieldemailHome Typestring | null ROyes DescriptionPersonal e-mail from the email multifield. Written through email
FieldemailMailing Typestring | null ROyes DescriptionMailing e-mail from the email multifield. Written through email
FieldphoneWork Typestring | null ROyes DescriptionWork phone from the phone multifield. Written through phone
FieldphoneMobile Typestring | null ROyes DescriptionMobile phone from the phone multifield. Written through phone
FieldphoneMailing Typestring | null ROyes DescriptionMailing phone from the phone multifield. Written through phone
Fieldimol Typestring | null ROyes DescriptionOpen Channel contact from the multifield collection
Fieldaddress Typestring | null ROyes DescriptionPhysical address as a single line. Edited in the company requisites
FieldaddressLegal Typestring | null ROyes DescriptionLegal address as a single line. Edited in the company requisites
FieldsearchContent Typestring | null ROyes DescriptionService field. A string Bitrix24 assembles from the card text for its own full-text search. Filtering by this field returns 400 UNKNOWN_FILTER_FIELD. For text search, filter title with $contains. Its composition can change without notice. Do not show it to users either

The eleven fields above arrive in list/get data but cannot be written directly: Bitrix24 returns a success response but does not store the value, so the platform refuses them with 400 READONLY_FIELD. Addresses are edited in the company requisites, and phone numbers and e-mail addresses are written through the phone and email multifields.

User fields (ufCrm*) are also returned and accepted. The set of such fields differs per Bitrix24 account, so they are not part of the static schema — their descriptions come from Bitrix24. For an enumeration field, this endpoint returns an array of options at data.fields.<field name>.items, shaped as { "ID": "3995", "VALUE": "warm" }. To write to a user field, send the ID, while VALUE is the option label for display. A label sent instead of the identifier is lost without an error. For details, see Value format by type.

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Company identifier." },
      "title": { "type": "string", "readonly": false, "label": "Name", "description": "Company name." },
      "assignedById": { "type": "number", "readonly": false, "label": "Responsible person", "description": "User responsible for the company." }
    },
    "relations": {
      "contact": { "type": "many", "entity": "contacts", "operations": ["list", "add", "remove", "set", "clear"] }
    },
    "activities": { "operations": ["list", "create"], "types": ["call", "meeting", "email", "task"] },
    "aggregatable": ["typeId", "industry", "revenue", "assignedById", "sourceId"],
    "batch": ["create", "update", "delete"],
    "import": { "method": "POST", "path": "/v1/companies/import", "maxItems": 100 },
    "include": ["contact"]
  }
}

Three fields from data.fields are shown, along with the other data keys. The full set of fields is in the tables above.

Error response example

403 — the key lacks the crm scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope",
    "hint": "This request needs the 'crm' scope, which the calling key does not carry. Add 'crm' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "crm",
    "keyScopes": ["task", "im"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "The app's API key lacks the “CRM” permission. You can add it in the key settings in the developer cabinet."
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

See also