Contact Fields in REST 3.0

Choose a tool for developing with an AI agent:

use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

These fields belong to REST 3.0 methods. The call specifics and response format of the new API version are described in the REST 3.0 overview.

Contact fields are returned by the crm.contact.get and crm.contact.list methods and accepted by the crm.contact.add and crm.contact.update methods. Values of multiple fields are added and removed one at a time by the crm.contact.addfieldvalue and crm.contact.deletefieldvalue methods. The list of fields with their attributes is returned by the crm.contact.field.list method.

Some fields exist in two forms: as an ID and as a related object, for example, assignedById and assignedBy. The ID can be passed when writing data, while the related object can only be requested in select.

Which Fields the Methods Accept and Return

Method	Accepts	Returns
crm.contact.add	Fields of the Contact Object table that can be edited, and custom fields. At least one of the `name` or `lastName` fields is required; otherwise, the method returns the error "At least one of name or lastName is required."	ID of the created contact `id`
crm.contact.update	Contact `id` and the same fields as `add`. Fields not included in `fields` keep their current values	Success flag `true`
crm.contact.get	Contact `id` and `select`	Without `select`, only `id`. With `select`, only the listed fields; `id` is not added automatically. A whole related object, for example, `assignedBy`, returns all of its fields, while a dot-notation path, for example, `assignedBy.firstName`, returns only the selected ones. For details, see the Related Objects section
crm.contact.list	`select`, `filter`, `order`, `pagination`	Without `select`, only the `id` of each contact. Fields and related objects are requested in `select` the same way as in `get`
crm.contact.addfieldvalue, crm.contact.deletefieldvalue	Contact `id`, the multiple field name `fieldName`, and the value `value`. Supported fields are `phone`, `email`, `web`, `im`, `companiesId`, `observersId`, and multiple custom fields. For other fields, the method returns the error "The field is not supported."	Success flag `true`

The add and update methods do not accept fields marked "read-only" and return the BITRIX_REST_V3_EXCEPTION_VALIDATION_DTOVALIDATIONEXCEPTION error with the message 'Field "companyId" is read-only.' Related objects, for example, company and assignedBy, are also read-only: to write data, pass the ID — companiesId, assignedById.

The method validates fields with values from reference lists when writing data. If the value is not in the reference list, the method returns the error 'Field value is not one of the possible values'. For the contact type, salutation, and source, the error message lists the allowed values.

Boolean fields accept and return true or false. The values Y, N, 1, and 0 are not accepted: the method returns the error 'This request requires data type "bool" in field "opened"'.

The birthdayTime field of the date type accepts and returns a date in the YYYY-MM-DD format, for example, 1990-05-15. The field does not accept a date with time or a date in the 15.05.1990 format. Fields of the datetime type are returned in ISO 8601 format, for example, 2026-11-03T14:42:28+03:00. In a filter by a datetime field, also pass a date with time.

You can filter and sort only by the fields whose description says so. For other fields, the list method returns an error stating that the field 'requires attribute "Filterable"' or '"Sortable"'. Dot notation lets you filter by fields of linked CRM items, of phone, email, website, and messenger values, and of the utm and lastCommunication objects, for example, ["company.title", "=", "Müller GmbH"] or ["phone.value", "=", "+49300000003"]. Filtering by fields of employees and reference lists, for example, assignedBy.id or type.name, is not supported: the method returns the BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION error. The filter format is described on the crm.<type>.list page and in the REST API 3.0 Overview article.

Filtering by the companiesId field does not work at the moment: the crm.contact.list method responds with HTTP status 500 and the INTERNAL_SERVER_ERROR error. To find the contacts of a company, filter by the primary company companyId or request the contactsId field of the company with the crm.company.get method.

Contact Object

Name `type`	Description
id `integer`	Contact ID. Assigned on creation. Read-only. Can be filtered and sorted
name `string`	First name, up to 50 characters. When creating a contact, `name` or `lastName` is required. Can be edited, filtered, and sorted
secondName `string`	Middle name, up to 50 characters. Can be edited, filtered, and sorted
lastName `string`	Last name, up to 50 characters. When creating a contact, `name` or `lastName` is required. Can be edited, filtered, and sorted
title `string`	Full name of the contact, which Bitrix24 builds from the last name, first name, and middle name, for example, `Weber Klaus Peter`. To change it, pass `name`, `secondName`, or `lastName`. Read-only. Cannot be filtered or sorted
honorificId `string`	Salutation ID, for example, `HNR_RU_1`. The values are returned by the crm.dictionary.honorific.list method. Can be edited, filtered, and sorted
honorific `object \| null`	Salutation. An object of type reference list value. Read-only. Requested in `select`
post `string`	Position, up to 255 characters. Can be edited, filtered, and sorted
birthdayTime `date \| null`	Date of birth in the `YYYY-MM-DD` format, for example, `1990-05-15`. Can be edited, filtered, and sorted
typeId `string`	Contact type ID, for example, `CLIENT`. The values are returned by the crm.dictionary.contacttype.list method. Can be edited, filtered, and sorted
type `object \| null`	Contact type. An object of type reference list value. Read-only. Requested in `select`
export `boolean`	Whether the contact is included in contact export: `true` — yes, `false` — no. Can be edited, filtered, and sorted
photo `object \| null`	Contact photo. An object of type file. To delete the photo, pass `null`. Can be edited. Cannot be filtered or sorted
companiesId `integer[]`	IDs of the contact's companies, up to 50 values. Companies are returned by the crm.company.list method. The passed array replaces the current list of companies. The first company in the array becomes the primary one and is written to `companyId`. Can be edited. A filter by this field currently returns the `INTERNAL_SERVER_ERROR` error, cannot be sorted
companies `object[]`	Contact companies. An array of objects of type CRM item. If there are no companies, an empty array. Read-only. Requested in `select`
companyId `integer \| null`	ID of the contact's primary company, which is the first one in the `companiesId` list. To change the primary company, pass it first in `companiesId`. Read-only. Can be filtered and sorted
company `object \| null`	Primary company of the contact. An object of type CRM item. Read-only. Requested in `select`
leadId `integer \| null`	ID of the lead from which the contact was created. If the contact was not created from a lead, `null`. Read-only. Can be filtered and sorted
lead `object \| null`	Lead from which the contact was created. An object of type CRM item. Read-only. Requested in `select`
phone `object[]`	Contact phone numbers. An array of objects of type multiple field value. Phone types are returned by the crm.dictionary.phonetype.list method. Can be edited. Can be filtered by value fields using dot notation, for example, `["phone.value", "=", "+49300000003"]`. Cannot be sorted
email `object[]`	Email addresses. An array of objects of type multiple field value. Email types are returned by the crm.dictionary.emailtype.list method. The method validates the address format and returns the error 'The field "Work E-mail" contains an incorrect address.' for an invalid address. Can be edited. Can be filtered by value fields using dot notation, for example, `email.value`. Cannot be sorted
web `object[]`	Websites and social media pages. An array of objects of type multiple field value. Website types are returned by the crm.dictionary.webtype.list method. Can be edited. Can be filtered by value fields using dot notation, for example, `web.value`. Cannot be sorted
im `object[]`	Messengers and open channels. An array of objects of type multiple field value. Messenger types are returned by the crm.dictionary.imtype.list method. Can be edited. Can be filtered by value fields using dot notation, for example, `im.value`. Cannot be sorted
hasPhone `boolean`	Whether the contact has at least one phone number: `true` — yes, `false` — no. Read-only. Cannot be filtered or sorted
hasEmail `boolean`	Whether the contact has at least one email address: `true` — yes, `false` — no. Read-only. Cannot be filtered or sorted
hasWeb `boolean`	Whether the contact has at least one website: `true` — yes, `false` — no. Read-only. Cannot be filtered or sorted
hasIm `boolean`	Whether the contact has at least one value in the `im` field: `true` — yes, `false` — no. Read-only. Cannot be filtered or sorted
sourceId `string \| null`	Source ID, for example, `WEB`. Sources are returned by the crm.dictionary.source.list method. Can be edited, filtered, and sorted
source `object \| null`	Source. An object of type reference list value. Read-only. Requested in `select`
sourceDescription `string \| null`	Additional information about the source. Can be edited and filtered, cannot be sorted
assignedById `integer`	ID of the person responsible for the contact. User IDs are returned by the user.get method. If the user does not exist, the method returns the error 'Field value is not one of the possible values'. Can be edited, filtered, and sorted
assignedBy `object`	Responsible person. An object of type employee. Read-only. Requested in `select`
observersId `integer[]`	Observer IDs. User IDs are returned by the user.get method. The passed array replaces the current list of observers. Can be edited and filtered, cannot be sorted. In a filter, `["observersId", "=", 1]` finds contacts that have user `1` among their observers
observers `object[]`	Observers. An array of objects of type employee. If there are no observers, an empty array. Read-only. Requested in `select`
opened `boolean`	Whether the contact is available to all users: `true` — yes, `false` — no. Can be edited, filtered, and sorted
comments `string \| null`	Comment on the contact. Can be edited. Cannot be filtered or sorted
utm `object`	UTM tags of the contact. An object of type UTM tags. Can be edited. Can be filtered by object fields using dot notation, for example, `["utm.source", "=", "google"]`. Cannot be sorted
trackingSourceId `integer \| null`	ID of the end-to-end analytics source. If the source does not exist or is archived, the method returns an error stating that the end-to-end analytics source was not found or is archived. Can be edited and filtered, cannot be sorted
originatorId `string \| null`	ID of the external system the contact was imported from. Use together with `originId` to link the contact to the record in the external system. Can be edited, filtered, and sorted
originId `string \| null`	Contact ID in the external system. Can be edited, filtered, and sorted
originVersion `string \| null`	Record version in the external system. Can be edited. Cannot be filtered or sorted
createdTime `datetime`	Date and time the contact was created. Read-only. Can be filtered and sorted
createdById `integer`	ID of the user who created the contact. The user data is in the `createdBy` object. Read-only. Can be filtered and sorted
createdBy `object`	User who created the contact. An object of type employee. Read-only. Requested in `select`
updatedTime `datetime`	Date and time the contact was last updated. Read-only. Can be filtered and sorted
updatedById `integer`	ID of the user who last updated the contact. Read-only. Can be filtered and sorted
updatedBy `object`	User who last updated the contact. An object of type employee. Read-only. Requested in `select`
lastActivityTime `datetime`	Date and time of the last activity in the contact timeline. Read-only. Can be filtered and sorted
lastActivityById `integer`	ID of the author of the last activity in the timeline. Read-only. Can be filtered and sorted
lastActivityBy `object`	Author of the last activity in the timeline. An object of type employee. Read-only. Requested in `select`
webformId `integer \| null`	ID of the CRM form through which the contact was created. If the contact was not created by a form, `null`. The list of forms is returned by the crm.form.list method. Read-only. Can be filtered and sorted
webform `object \| null`	CRM form through which the contact was created. An object of type CRM form. Read-only. Requested in `select`
lastCommunication `object`	Dates of the last communications with the contact. An object of type last communication. Read-only. Requested in `select`. Can be filtered by object fields using dot notation, for example, `["lastCommunication.callTime", ">=", "2026-11-01T00:00:00+03:00"]`
entityTypeId `integer`	Object type ID. For a contact, `3`. Read-only
canRead `boolean`	Whether the current user can view the contact: `true` — yes, `false` — no. Read-only
url `string`	Relative link to the contact card, for example, `/crm/contact/details/3211/`. Read-only

Phone Numbers, Email, Websites, and Messengers

The phone, email, web, and im fields are arrays of values. Each value is an object with the following fields:

Name `type`	Description
id `integer`	Value ID. Assigned when writing data and cannot be passed: the method returns the error 'Field "id" is read-only.'
valueTypeId `string`	Value type, for example, `WORK` or `MOBILE`. Required when writing data. The allowed types for each field are returned by the crm.dictionary.phonetype.list, crm.dictionary.emailtype.list, crm.dictionary.webtype.list, and crm.dictionary.imtype.list methods
valueType `object`	Value type with its name: `id`, `name` — full name, for example, `Mobile`, `nameShort` — short name, for example, `Mobile`. Read-only
value `string`	Value: phone number, email address, website address, or messenger ID. Required when writing data

When writing data, pass an array of objects with the valueTypeId and value fields:

{
            "phone": [
                {"valueTypeId": "WORK", "value": "+49300000001"},
                {"valueTypeId": "MOBILE", "value": "+49300000002"}
            ]
        }

In the response, each value is returned with id and the valueType object:

{
            "phone": [
                {
                    "id": 8871,
                    "valueTypeId": "MOBILE",
                    "valueType": {
                        "id": "MOBILE",
                        "name": "Mobile",
                        "nameShort": "Mobile"
                    },
                    "value": "+49300000003"
                }
            ]
        }

How writing works:

crm.contact.update replaces all values of the field with the passed array. Values not included in the array are deleted. Other multiple fields not included in fields do not change
an empty array, for example, "phone": [], deletes all values of the field
a single value is added by the crm.contact.addfieldvalue method and deleted by crm.contact.deletefieldvalue. In value, pass the object {"valueTypeId": "MOBILE", "value": "+49300000008"}. If such a value already exists, addfieldvalue returns the error "The field value already exists."
one field can contain up to 50 values, and all four fields together up to 100. If the limit is exceeded, the method returns the error "Too many phone multifields."

File Object

Field photo. To upload a photo, pass the upload object with the file name and the content in Base64 or a link to the file:

{
            "photo": {
                "upload": {
                    "name": "photo.png",
                    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=="
                }
            }
        }

Instead of data, you can pass url — the file address. You cannot pass data and url at the same time.

In the response, the field contains the data of the uploaded file:

Name `type`	Description
id `string`	File ID, for example, `"39933"`
name `string`	File name
url `string`	Address for viewing the file in Bitrix24
downloadUrl `string`	Address for downloading the file via REST. The address contains the webhook authorization data, do not publish it

UTM Tags Object

Field utm. When writing data, pass only the tags you need: on creation, the other tags are set to null; on update, they keep their current values. Each tag is a string of up to 255 characters.

Name `type`	Description
source `string \| null`	Ad platform, the `utm_source` tag, for example, `google`
medium `string \| null`	Traffic type, the `utm_medium` tag, for example, `cpc`
campaign `string \| null`	Ad campaign, the `utm_campaign` tag
content `string \| null`	Ad content, the `utm_content` tag
term `string \| null`	Keyword, the `utm_term` tag

Related Objects

A related object is requested in select by the field name without the Id suffix: assignedBy, honorific, company. The whole object name returns all of its fields, and a dot-notation path returns only the selected ones, for example, ["type.name", "assignedBy.firstName"]. The path supports one level of nesting: the method does not accept company.createdBy.firstName.

A linked CRM item — company, companies, lead — returns only id when requested by its whole name. Request the other item fields using dot notation. Dot notation gives access to the fields of the CRM item object and to any fields of the linked item's type, for example, ["company.title", "company.phone", "company.industryId"]. Company fields are described in the Company Fields in REST 3.0 article.

If a link is not set, the object is returned as null, and an array of objects, for example, observers or companies, is returned as an empty array.

Employee Object

Fields createdBy, updatedBy, lastActivityBy, assignedBy, observers.

Name `type`	Description
id `integer`	User ID
firstName `string`	First name
lastName `string`	Last name
personalGender `string \| null`	Gender: `M` — male, `F` — female. If the gender is not specified, `null`
url `string`	Relative link to the user profile, for example, `/company/personal/user/1/`
personalPhoto `string \| null`	Link to the user photo. If there is no photo, `null`

CRM Item Object

Fields company, companies, lead.

Name `type`	Description
id `integer`	Item ID
entityTypeId `integer`	Object type ID: `4` — company, `1` — lead
canRead `boolean`	Whether the current user can view the item
title `string`	Item title
url `string`	Relative link to the item card, for example, `/crm/company/details/3159/`

Reference List Value Object

Fields honorific, type, source.

Name `type`	Description
id `string`	Value ID, for example, `CLIENT`
name `string`	Value name, for example, `Clients`
sort `integer`	Sort order

CRM Form Object

Field webform.

Name `type`	Description
id `integer`	CRM form ID
name `string`	CRM form name

Last Communication Object

Field lastCommunication. If there has been no communication of a given kind, the corresponding field is null.

Name `type`	Description
communicationTime `datetime \| null`	Date and time of the last communication of any kind
callTime `datetime \| null`	Date and time of the last call
emailTime `datetime \| null`	Date and time of the last email
imolTime `datetime \| null`	Date and time of the last message in an open channel
webformTime `datetime \| null`	Date and time the CRM form was last submitted

Custom Fields

Custom contact fields are named UF_CRM_<code>, for example, UF_CRM_1716289811. They are passed and requested by name in the same way as standard fields. The list of custom contact fields is returned by the crm.contact.field.custom.list method.

The value of a "Money" field is passed as an object {"sum": 150.5, "currencyId": "EUR"}. A string such as 150.5|EUR is not accepted: the method returns the error 'This request requires data type "MoneyDto" in field "UF_CRM_…"'.

Each custom field has a paired UF_CRM_…_data field, which is read-only and requested in select. It contains the value in several representations:

value — the value in the same format as in the field itself
rawValue — the value in the storage format, for example, 150.5|EUR for a "Money" field
formattedValue — the value for display to the user: 150.50 € for money, the employee name for a "Link to employee" field
extra — additional data: for money, amount, currencyId, and currencyFullName; for an employee, the fields of the employee object. For a string, number, and date, null

For a multiple custom field, UF_CRM_…_data is an array of such objects.

Continue Learning

Was the article helpful?

Lead Fields

Company Fields

Contact Fields in REST 3.0

Which Fields the Methods Accept and ReturnWhich Fields the Methods Accept and Return

Contact ObjectContact Object

Phone Numbers, Email, Websites, and MessengersPhone Numbers, Email, Websites, and Messengers

File ObjectFile Object

UTM Tags ObjectUTM Tags Object

Related ObjectsRelated Objects

Employee ObjectEmployee Object

CRM Item ObjectCRM Item Object

Reference List Value ObjectReference List Value Object

CRM Form ObjectCRM Form Object

Last Communication ObjectLast Communication Object

Custom FieldsCustom Fields

Continue LearningContinue Learning