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

SPA item fields are returned by the crm.smartprocess<entityTypeId>.get and crm.smartprocess<entityTypeId>.list methods and accepted by the crm.smartprocess<entityTypeId>.add and crm.smartprocess<entityTypeId>.update methods. The method name includes the SPA type ID entityTypeId, for example, crm.smartprocess1038.get. Type IDs and settings are returned by the crm.type.list method.

The set of fields depends on the SPA type settings: without pipelines, an item has no categoryId, and without stages, it has no stageId and other stage fields. For such fields, the SPA Object table specifies which type setting is required. The list of fields of a specific type is returned by the crm.smartprocess<entityTypeId>.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.smartprocess<entityTypeId>.add

Fields of the SPA Object table that can be edited, and custom fields. There are no required fields: an item is created even with an empty fields object

ID of the created item id

crm.smartprocess<entityTypeId>.update

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

Success flag true

crm.smartprocess<entityTypeId>.get

Item 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.smartprocess<entityTypeId>.list

select, filter, order, pagination

Without select, only the id of each item. 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 "contactId" 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, 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, 2026-11-03. Such a field does not accept a date with time or a date in the 03.11.2026 format. Fields of the datetime type are returned in ISO 8601 format, for example, 2026-11-03T14:47:23+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 and of the lastCommunication object, for example, ["company.title", "=", "Müller GmbH"]. Filtering by fields of employees, stage, pipeline, 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, stageSemanticId, and stageSemantic fields are present in the crm.smartprocess<entityTypeId>.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. The stage group can be retrieved from the semanticId field of the stage object: "select": ["stage.semanticId"].

SPA Object

Name
type

Description

title
string

Item title, up to 255 characters. If the title is not passed on creation, Bitrix24 sets a title in the <type name> #<id> format.

Can be edited, filtered, and sorted

xmlId
string

External code of the item, up to 255 characters. Use it to link the item to a record in an external system.

Can be edited, filtered, and sorted

id
integer

Item ID. Assigned on creation.

Read-only. Can be filtered and sorted

createdTime
datetime

Date and time the item was created.

Read-only. Can be filtered and sorted

createdById
integer

ID of the user who created the item.

Read-only. Can be filtered and sorted

createdBy
object

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

Read-only. Requested in select

updatedTime
datetime

Date and time the item was last updated.

Read-only. Can be filtered and sorted

updatedById
integer

ID of the user who last updated the item.

Read-only. Can be filtered and sorted

updatedBy
object

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

Read-only. Requested in select

lastActivityTime
datetime

Date and time of the last activity in the item 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 item. 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 item is available to all users: true — yes, false — no.

Can be edited, filtered, and sorted

webformId
integer | null

ID of the CRM form through which the item was created. If the item 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 item 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 item. 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

SPA type ID, for example, 1038.

Read-only

canRead
boolean

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

Read-only

url
string

Relative link to the item card, for example, /crm/type/1038/details/29/?categoryId=69.

Read-only

stageId
string

Stage ID, for example, DT1038_69:NEW. The stage must belong to the item's pipeline. Pipeline stages are returned by the crm.smartprocess<entityTypeId>.category.stage.list method.

Can be edited, filtered, and sorted.

Available if stages are enabled in the type settings: isStagesEnabled

stage
object

Item stage. An object of type stage.

Read-only. Requested in select.

Available if stages are enabled in the type settings: isStagesEnabled

movedTime
datetime

Date and time of the last stage change.

Read-only. Can be filtered and sorted.

Available if stages are enabled in the type settings: isStagesEnabled

movedById
integer

ID of the user who last changed the stage.

Read-only. Can be filtered and sorted.

Available if stages are enabled in the type settings: isStagesEnabled

movedBy
object

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

Read-only. Requested in select.

Available if stages are enabled in the type settings: isStagesEnabled

closed
boolean

Whether the item is closed: true — yes, false — no.

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.

Available if stages are enabled in the type settings: isStagesEnabled

stageSemanticId
string

Stage group. Possible values:

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

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 stage group is returned by the stage.semanticId field.

Available if stages are enabled in the type settings: isStagesEnabled

stageSemantic
object

Stage group with its name: id and name. The reference list of groups is returned by the crm.dictionary.stagesemantic.list method.

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.

Available if stages are enabled in the type settings: isStagesEnabled

beginTime
date

Start date. If not passed on creation, Bitrix24 sets the item creation date.

Can be edited, filtered, and sorted.

Available if start and end dates are enabled in the type settings: isBeginCloseDatesEnabled

closeTime
date

End date. If not passed on creation, Bitrix24 sets the date seven days after the item is created.

Can be edited, filtered, and sorted.

Available if start and end dates are enabled in the type settings: isBeginCloseDatesEnabled

categoryId
integer

Pipeline ID. If not passed on creation, the item is placed in the default pipeline. Type pipelines are returned by the crm.smartprocess<entityTypeId>.category.list method.

Can be edited, filtered, and sorted.

Available if pipelines are enabled in the type settings: isCategoriesEnabled

category
object

Item pipeline. An object of type pipeline.

Read-only. Requested in select.

Available if pipelines are enabled in the type settings: isCategoriesEnabled

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 items that have user 1 among their observers.

Available if observers are enabled in the type settings: isObserversEnabled

observers
object[]

Observers. An array of objects of type employee. If there are no observers, an empty array.

Read-only. Requested in select.

Available if observers are enabled in the type settings: isObserversEnabled

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.smartprocess<entityTypeId>.setprimarycontact method.

Read-only. Can be filtered, cannot be sorted.

Available if the client link is enabled in the type settings: isClientEnabled

contact
object | null

Primary contact. An object of type CRM item.

Read-only. Requested in select.

Available if the client link is enabled in the type settings: isClientEnabled

contactsId
integer[]

IDs of the item contacts. 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.

Available if the client link is enabled in the type settings: isClientEnabled

contacts
object[]

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

Read-only. Requested in select.

Available if the client link is enabled in the type settings: isClientEnabled

companyId
integer | null

Company ID. Companies are returned by the crm.company.list method.

Can be edited, filtered, and sorted.

Available if the client link is enabled in the type settings: isClientEnabled

company
object | null

Company. An object of type CRM item.

Read-only. Requested in select.

Available if the client link is enabled in the type settings: isClientEnabled

myCompanyId
integer | null

ID of your company, on whose behalf you work with the client. The list of your companies is returned by the crm.mycompany.list method.

Can be edited, filtered, and sorted.

Available if your company requisites are enabled in the type settings: isMycompanyEnabled

myCompany
object | null

Your company. An object of type CRM item.

Read-only. Requested in select.

Available if your company requisites are enabled in the type settings: isMycompanyEnabled

sourceId
string

Source ID, for example, CALL. Sources are returned by the crm.dictionary.source.list method.

Can be edited, filtered, and sorted.

Available if the source field is enabled in the type settings: isSourceEnabled

source
object | null

Source. An object of type reference list value.

Read-only. Requested in select.

Available if the source field is enabled in the type settings: isSourceEnabled

sourceDescription
string

Additional information about the source.

Can be edited and filtered, cannot be sorted.

Available if the source field is enabled in the type settings: isSourceEnabled

opportunity
double

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

Can be edited, filtered, and sorted.

Available if product linking is enabled in the type settings: isLinkWithProductsEnabled

taxValue
double

Tax amount. Calculated from the product rows.

Read-only. Can be filtered and sorted.

Available if product linking is enabled in the type settings: isLinkWithProductsEnabled

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.

Available if product linking is enabled in the type settings: isLinkWithProductsEnabled

currencyId
string

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

Can be edited, filtered, and sorted.

Available if product linking is enabled in the type settings: isLinkWithProductsEnabled

currency
object

Currency. An object of type currency.

Read-only. Requested in select.

Available if product linking is enabled in the type settings: isLinkWithProductsEnabled

related<type code>Id
integer | null

ID of the parent item of another object type, for example, relatedLeadId, relatedSmartInvoiceId, 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, relatedLead. 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 SPA is subordinate to another object type. For each parent type, the SPA has a pair of fields:

  • related<type code>Id — ID of the parent item, for example, relatedLeadId for a lead, relatedSmartInvoiceId for an invoice, relatedSmartProcess177Id for the SPA with entityTypeId = 177
  • related<type code> — the parent item as an object of type CRM item, for example, relatedLead

The field title in the field.list response matches the name of the parent type, for example, "Lead" or "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'.

Each type has its own set of these fields. The current list is returned by the crm.smartprocess<entityTypeId>.field.list method.

Related Objects

A related object is requested in select by the field name without the Id suffix: assignedBy, stage, category. 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, myCompany, 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 or contacts, 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, myCompany, 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/

Stage Object

Field stage.

Name
type

Description

id
string

Stage ID, for example, DT1038_69:NEW

name
string

Stage name

sort
integer

Stage order in the pipeline

color
string

Stage color in the #RRGGBB format

semanticId
string

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

Pipeline Object

Field category.

Name
type

Description

id
integer

Pipeline ID

name
string

Pipeline name

sort
integer

Pipeline sort order

isDefault
boolean

Default pipeline: true — yes, false — no

Reference List Value Object

Field 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

Custom Fields

Custom SPA fields are named UF_CRM_<type id>_<code>, for example, UF_CRM_3_1628508893. The name contains the type ID id, not entityTypeId: the field in the example belongs to the type with id = 3 and entityTypeId = 174. Both IDs are returned by the crm.type.list method. Custom fields are passed and requested by name in the same way as standard fields. The list of custom fields of the type is returned by the crm.smartprocess<entityTypeId>.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
Invoice Fields
Next
My Company Fields