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

Contact fields

GET /v1/contacts/fields

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

Examples

curl — personal key

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

curl — OAuth application

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

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/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 contact field schema and the operations available for contacts. Its keys are in the rows below
Fielddata.fields Typeobject DescriptionThe contact field schema: field name → an object with type, readonly and label. Some fields also carry description and extra attributes such as nullable, multiple, maxLength and items. The standard fields are listed below, and the ufCrm* user fields of this Bitrix24 account are added to them
Fielddata.relations Typeobject DescriptionRelations with companies: company is the primary company, companyBinding covers all linked companies and the operations on them. See Contact companies
Fielddata.activities Typeobject DescriptionContact 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, sourceId, assignedById
Fielddata.batch Typearray DescriptionContact 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: company, companyBinding

Standard contact fields

Field Type RO Description
Fieldid Typenumber ROyes DescriptionContact ID
Fieldname Typestring RO DescriptionFirst name, at most 50 Unicode code points. Longer values are rejected before writing; the name is not truncated.
FieldlastName Typestring RO DescriptionLast name
FieldsecondName Typestring RO DescriptionMiddle name
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 — old phone entries are not removed. See Update contact. Important: The uppercase 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.
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 — old email entries are not removed. Important: The uppercase 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.
FieldphoneWork Typestring ROyes DescriptionWork phone expanded from the phone multifield. Read-only: a number is written through phone; no write operation saves a submitted value, so the write is rejected: create and update — 400 READONLY_FIELD, import — 400 IMPORT_ITEM_VALIDATION, entity batch — 400 BATCH_ITEM_VALIDATION, global batch — READONLY_FIELD under the call. null when there is no such number. Filter (exact and $contains) and sorting work
FieldphoneMobile Typestring ROyes DescriptionMobile phone expanded from the phone multifield. Read-only, like phoneWork. null when there is no such number
FieldphoneMailing Typestring ROyes DescriptionMailing phone expanded from the phone multifield. Read-only, like phoneWork. null when there is no such number
Fieldimol Typestring ROyes DescriptionOpen Channel (messenger) contact of the person, expanded from the multifield collection. Read-only. null when there is none
Fieldaddress Typestring ROyes DescriptionAddress of the contact as a single line (legacy column). Bitrix24 returns it but does not store it through the item API used by this method: no write operation saves a submitted value, and the request is rejected (codes as for phoneWork); only the legacy crm.contact.add of older integrations fills it, and an address is edited in the contact's requisites. null when not filled in. Filter (exact and $contains) and sorting work
FieldshortName Typestring ROyes DescriptionShort name — last name with initials ("Smith J. R."), computed by Bitrix24. Returned only in list or search results when the field is explicitly named in select (without *); a single GET /v1/contacts/{id}, a list without select and the entity batch list (its select is a projection) return null. Read-only (the same error codes as for phoneWork). Filter (exact and $contains) and sorting work
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
FieldcompanyId Typenumber RO DescriptionCompany ID. Lookup: GET /v1/companies
Fieldpost Typestring RO DescriptionPosition
Fieldcomments Typestring RO DescriptionComment
FieldtypeId Typestring RO DescriptionContact type. List: GET /v1/statuses?filter[entityId]=CONTACT_TYPE
FieldsourceId Typestring RO DescriptionSource. List: GET /v1/statuses?filter[entityId]=SOURCE
FieldsourceDescription Typestring RO DescriptionSource description
FieldassignedById Typenumber RO DescriptionAssignee. 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
Fieldexport Typeboolean RO DescriptionExport allowed
FieldleadId Typenumber RO DescriptionSource lead ID
Fieldhonorific Typestring RO DescriptionSalutation. List: GET /v1/statuses?filter[entityId]=HONORIFIC

User fields (ufCrm*) are also returned in responses and accepted on create/update. For an enumeration field, this endpoint returns an array of options at data.fields.<field name>.items, shaped as { "ID": "3989", "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": "Contact identifier." },
      "name": { "type": "string", "readonly": false, "maxLength": 50, "label": "First name", "description": "Contact's first name, up to 50 characters. A longer value is refused before writing instead of being silently shortened." },
      "assignedById": { "type": "number", "readonly": false, "label": "Responsible person", "description": "User responsible for the contact." }
    },
    "relations": {
      "company": { "type": "one", "entity": "companies", "includable": true },
      "companyBinding": { "type": "many", "entity": "companies", "operations": ["list", "add", "remove", "set", "clear"] }
    },
    "activities": { "operations": ["list", "create"], "types": ["call", "meeting", "email", "task"] },
    "aggregatable": ["typeId", "sourceId", "assignedById"],
    "batch": ["create", "update", "delete"],
    "import": { "method": "POST", "path": "/v1/contacts/import", "maxItems": 100 },
    "include": ["company", "companyBinding"]
  }
}

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

What to do with the names from data.include is covered on the Get contact page. For more information about the include parameter, see Related data.

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 DescriptionAPI key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI 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