Lead 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.

Lead fields are returned by the crm.lead.get and crm.lead.list methods and accepted by the crm.lead.add and crm.lead.update methods. The list of fields with their attributes is returned by the crm.lead.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.lead.add

Fields of the Lead Object table that can be edited, and custom fields. The required field is title

ID of the created lead id

crm.lead.update

Lead id and the same fields as add. Fields not included in fields keep their current values

Success flag true

crm.lead.get

Lead 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.lead.list

select, filter, order, pagination

Without select, only the id of each lead. Fields and related objects are requested in select the same way as in get

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 "hasPhone" is read-only.' Related objects, for example, company and stage, are also read-only: to write data, pass the ID — companyId, stageId.

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 stage, salutation, source, and currency, 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"'.

Fields of the date type accept and return a date in the YYYY-MM-DD format, for example, 1990-05-15. Such a 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:48:48+03:00. In a filter by a datetime field, also pass a date with time: the method does not accept the value 2026-11-03.

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 lastCommunication and utm objects, for example, ["company.title", "=", "Müller GmbH"] or ["im.valueTypeId", "=", "IMOL"]. Filtering by fields of employees, stage, and source, for example, assignedBy.id or stage.semanticId, 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.

The closed and taxValue fields are present in the crm.lead.field.list response, but the get and list methods do not accept them. For such a field in select, filter, or order, the method returns the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error.

Lead Object

Name
type

Description

title
string

Lead title, up to 255 characters. Required for creating a lead.

Can be edited, filtered, and sorted

honorificId
string | null

Salutation ID, for example, HNR_RU_1. Salutations 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

name
string | null

First name, up to 50 characters.

Can be edited, filtered, and sorted

secondName
string | null

Middle name, up to 50 characters.

Can be edited, filtered, and sorted

lastName
string | null

Last name, up to 50 characters.

Can be edited, filtered, and sorted

post
string | null

Position, up to 255 characters.

Can be edited, filtered, and sorted

companyTitle
string | null

Name of the client's company, up to 255 characters. This is text in the lead card, not a link to a CRM company — the link is set by the companyId field.

Can be edited, filtered, and sorted

birthdayTime
date | null

Date of birth.

Can be edited, filtered, and sorted

statusDescription
string | null

Additional information about the lead stage.

Can be edited, filtered, and sorted

id
integer

Lead ID. Assigned on creation.

Read-only. Can be filtered and sorted

createdTime
datetime

Date and time the lead was created.

Read-only. Can be filtered and sorted

createdById
integer

ID of the user who created the lead.

Read-only. Can be filtered and sorted

createdBy
object

User who created the lead. An object of type employee.

Read-only. Requested in select

updatedTime
datetime

Date and time the lead was last updated.

Read-only. Can be filtered and sorted

updatedById
integer

ID of the user who last updated the lead.

Read-only. Can be filtered and sorted

updatedBy
object

User who last updated the lead. An object of type employee.

Read-only. Requested in select

lastActivityTime
datetime

Date and time of the last activity in the lead 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

assignedById
integer

ID of the person responsible for the lead. 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

opened
boolean

Whether the lead is available to all users: true — yes, false — no.

Can be edited, filtered, and sorted

comments
string | null

Comment on the lead. Supports BB codes, for example, [b]text[/b].

Can be edited. Cannot be filtered or sorted

originatorId
string | null

ID of the external system the lead came from. Use together with originId to link the lead to an external source.

Can be edited, filtered, and sorted

originId
string | null

Lead ID in the external system.

Can be edited, filtered, and sorted

webformId
integer | null

ID of the CRM form through which the lead was created. If the lead 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 lead was created. An object of type CRM form.

Read-only. Requested in select

lastCommunication
object

Dates of the last communications with the client on the lead. An object of type last communication.

Read-only. Requested in select. Can be filtered by object fields using dot notation, for example, ["lastCommunication.imolTime", ">=", "2026-11-01T00:00:00+03:00"]

entityTypeId
integer

Object type ID. For a lead, 1.

Read-only

canRead
boolean

Whether the current user can view the lead: true — yes, false — no.

Read-only

url
string

Relative link to the lead card, for example, /crm/lead/details/1001253/.

Read-only

stageId
string

Lead stage ID, for example, NEW, IN_PROCESS, CONVERTED. Leads have a single pipeline. Lead stages are returned by the crm.status.list method with the ENTITY_ID = STATUS filter.

Can be edited, filtered, and sorted

stage
object

Lead stage. An object of type stage.

Read-only. Requested in select

movedTime
datetime

Date and time of the last stage change.

Read-only. Can be filtered and sorted

movedById
integer

ID of the user who last changed the stage.

Read-only. Can be filtered and sorted

movedBy
object

User who last changed the stage. An object of type employee.

Read-only. Requested in select

closed
boolean

Whether the lead is closed.

Read-only. The field is present in the field.list response, but the get and list methods do not accept it and return the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error. The lead stage group is returned by the stageSemanticId field

stageSemanticId
string

Stage group. Possible values:

  • P — in progress
  • S — successful
  • F — unsuccessful

Read-only. Can be filtered and sorted

stageSemantic
object

Stage group with its name. An object of type stage group.

Read-only. Requested in select

observersId
integer[]

Observer IDs. User IDs are returned by the user.get method.

Can be edited and filtered, cannot be sorted. In a filter, ["observersId", "=", 1] finds leads 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

contactId
integer | null

ID of the primary contact, which is the first one in the contactsId list. To set the primary contact, use the crm.lead.setprimarycontact method.

Read-only. Can be filtered, cannot be sorted

contact
object | null

Primary contact. An object of type CRM item.

Read-only. Requested in select

contactsId
integer[]

IDs of the contacts the lead is linked to. Contacts are returned by the crm.contact.list method. The passed array replaces the current list of contacts.

Can be edited and filtered, cannot be sorted

contacts
object[]

Lead contacts. An array of objects of type CRM item. If there are no contacts, an empty array.

Read-only. Requested in select

companyId
integer | null

ID of the CRM company the lead is linked to. Companies are returned by the crm.company.list method.

Can be edited, filtered, and sorted

company
object | null

Company. An object of type CRM item.

Read-only. Requested in select

sourceId
string | null

Source ID, for example, CALL. 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

opportunity
double

Lead amount, not less than 0. The way the amount is calculated is set by the isManualOpportunity field.

Can be edited, filtered, and sorted

taxValue
double

Tax amount.

Read-only. The field is present in the field.list response, but the get and list methods do not accept it and return the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error

isManualOpportunity
boolean

Amount calculation mode: true — the amount is set manually, false — the amount is calculated from the product rows.

Can be edited, filtered, and sorted

currencyId
string

Currency ID, for example, EUR. Currencies are returned by the crm.currency.list method.

Can be edited, filtered, and sorted

currency
object

Currency. An object of type currency.

Read-only. Requested in select

phone
object[]

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: the passed array replaces all phone numbers of the lead, for example, [{"valueTypeId": "WORK", "value": "+49300000001"}]. Can be filtered by object fields using dot notation, for example, ["phone.value", "=", "+49300000001"], 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.

Can be edited: the passed array replaces all email addresses of the lead. Can be filtered by object fields using dot notation, cannot be sorted

web
object[]

Websites. An array of objects of type multiple field value. Website types are returned by the crm.dictionary.webtype.list method.

Can be edited: the passed array replaces all websites of the lead. Can be filtered by object fields using dot notation, 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: the passed array replaces all values of this field. Can be filtered by object fields using dot notation, for example, ["im.valueTypeId", "=", "IMOL"], cannot be sorted

hasPhone
boolean

Whether the lead has at least one phone number: true — yes, false — no.

Read-only. Cannot be filtered or sorted

hasEmail
boolean

Whether the lead has at least one email address: true — yes, false — no.

Read-only. Cannot be filtered or sorted

hasWeb
boolean

Whether the lead has at least one website: true — yes, false — no.

Read-only. Cannot be filtered or sorted

hasIm
boolean

Whether the lead has at least one value in the im field: true — yes, false — no.

Read-only. Cannot be filtered or sorted

utm
object | null

UTM tags of the lead. An object of type UTM tags. If there are no tags, null.

Can be edited: pass an object with the tags you need, for example, {"source": "google", "medium": "cpc"}. 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.

Can be edited and filtered, cannot be sorted

related<type code>Id
integer | null

ID of the parent item of another object type, for example, relatedSmartProcess177Id. For details, see the Fields Linking to Other Types section.

Can be edited and filtered, cannot be sorted

related<type code>
object | null

Parent item of another object type, for example, relatedSmartProcess177. An object of type CRM item.

Read-only. Requested in select

The related<type code>Id and related<type code> fields appear when Bitrix24 has a link configured in which the lead is subordinate to another object type, for example, an SPA. For each parent type, the lead has a pair of fields:

  • related<type code>Id — ID of the parent item, for example, relatedSmartProcess177Id for the SPA with entityTypeId = 177
  • related<type code> — the parent item as an object of type CRM item, for example, relatedSmartProcess177

The field title in the crm.lead.field.list response matches the name of the parent type, for example, "Equipment purchase". The method checks that an item with the passed ID exists. If there is no such item, the method returns the error 'Field value is not one of the possible values'.

The set of these fields depends on the links configured in Bitrix24. The current list is returned by the crm.lead.field.list method.

Related Objects

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

A linked CRM item — contact, company, related<type code> — returns only id when requested by its whole name. Request the other item fields using dot notation, for example, ["company.title", "company.url"].

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

Employee Object

Fields createdBy, updatedBy, lastActivityBy, assignedBy, movedBy, 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 contact, contacts, company, related<type code>.

Name
type

Description

id
integer

Item ID

entityTypeId
integer

Object type ID, for example, 3 — contact, 4 — company

canRead
boolean

Whether the current user can view the item

title
string

Item title. For a contact, the last name, first name, and middle name

url
string

Relative link to the item card, for example, /crm/company/details/3/

Phone Numbers, Email, Websites, and Messengers

Fields phone, email, web, im. When writing data, pass valueTypeId and value, both are required. If the value type is not in the reference list, the method returns the error 'Field value is not one of the possible values'.

Name
type

Description

id
integer

Value ID. Assigned when writing data; when the list is replaced, the values receive new IDs

valueTypeId
string

Value type, for example, WORK or MOBILE for a phone number

valueType
object

Value type with its name: id, name — full name, nameShort — short name. Read-only

value
string

Value: phone number, email address, website address, or messenger ID

Stage Object

Field stage.

Name
type

Description

id
string

Stage ID, for example, NEW

name
string

Stage name

sort
integer

Stage order

color
string

Stage color in the #RRGGBB format

semanticId
string

Stage group: P — in progress, S — successful, F — unsuccessful

Stage Group Object

Field stageSemantic. The reference list of groups is returned by the crm.dictionary.stagesemantic.list method.

Name
type

Description

id
string

Group ID: P, S, or F

name
string

Group name, for example, Stage group "Lead in progress"

Reference List Value Object

Fields honorific and source.

Name
type

Description

id
string

Value ID, for example, CALL

name
string

Value name, for example, Call

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

Currency Object

Field currency.

Name
type

Description

id
string

Currency code, for example, EUR

fullName
string

Currency name

formatString
string

Amount display template. The # character is replaced with the amount. The currency sign is returned as an HTML entity, for example, &euro;#

decPoint
string

Decimal separator

thousandsSep
string

Thousands separator. May be returned as an HTML entity, for example, &nbsp;

decimals
integer

Number of decimal places

hideZero
boolean

Whether to hide insignificant trailing zeros in the fractional part

amount
double

Exchange rate relative to the base currency

amountCount
integer

Number of currency units the exchange rate applies to

base
boolean

Base currency: true — yes, false — no

sort
integer

Sort order

numericCode
string

Numeric currency code, for example, 978

languageId
string

Language for which the name and format are set

createdTime
datetime | null

Date and time the currency was created

updatedTime
datetime | null

Date and time the currency was updated

createdById
integer | null

ID of the user who created the currency

updatedById
integer | null

ID of the user who updated the currency

UTM Tags Object

Field utm. Each tag is a string of up to 255 characters. Tags that were not passed are returned as null.

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

Custom Fields

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

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, 100.5|EUR for a "Money" field
  • formattedValue — the value for display to the user: 100.50 € for money, the employee name for a "Link to employee" field, the option text for a list
  • extra — additional data: for money, amount, currencyId, and currencyFullName; for an employee, the fields of the employee object. For a string, date, and list, null

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

Continue Learning

Previous
Deal Fields
Next
Contact Fields