API changes: November 3, 2026

← Changelog · November 2026

NEW-1103-1: CRM e-mails and settings through the API

The VibeCode API can read CRM activity e-mails, get content and conversation threads, send e-mails and reply to them. Reading requires the crm scope; sending requires write access and sends a real e-mail. Never blindly repeat a send after an ambiguous failure.

CRM settings can be read and changed. A change affects CRM for the entire Bitrix24 account. Send the complete value matching the schema from the read response. A failed readback does not undo a successful write.

Affected endpoints: GET /v1/crm-settings, GET /v1/crm-settings/:id, PATCH /v1/crm-settings/:id, GET /v1/deals/:id/emails, POST /v1/deals/:id/emails, GET /v1/crm-emails/:activityId, GET /v1/crm-emails/:activityId/thread, POST /v1/crm-emails/:activityId/reply. Listing and sending also support leads, contacts, companies. Existing GET /v1/crm-settings/mode is preserved.

NEW-1103-2: Individual CRM field values and the primary contact

Added field value operations: POST and DELETE /v1/<resource>/:id/fields/:field/values change one value without replacing the whole list. PUT /v1/<resource>/:id/primary-contact chooses an already bound contact as primary. Requires crm scope, a key with write access and the crm-rest-v3 feature enabled.

Methods require RestV3CrudDeal enabled in a Bitrix24 update after crm 26.2200.0. Until available, the API returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

NEW-1103-3: Required CRM fields

GET|PUT|DELETE /v1/{deals,leads,contacts,companies,quotes,invoices}/fields/required and /v1/items/:entityTypeId/fields/required read, set and clear the requirement through REST v3. Scope crm. Writes require READWRITE and affect CRM cards and record saving for all users of the Bitrix24 account. When the feature is off or the method is unavailable, the response is 422 METHOD_NOT_YET_AVAILABLE with the release line in error.release.

NEW-1103-4: CRM dictionaries, list field options, funnel stages and lead mode

The VibeCode API now reads CRM dictionaries with GET /v1/crm-dictionaries/:dictionary, manages individual list field options through /v1/userfields/:entity/enum-values and /v1/items/:entityTypeId/userfields/enum-values, and replaces stages with PUT /v1/deal-categories/:categoryId/stages and PUT /v1/categories/:entityTypeId/:categoryId/stages.

POST /v1/leads/enable and POST /v1/leads/disable switch the entire Bitrix24 account between classic and simple CRM. Writes require READWRITE. System and final stages remain, and deleting a stage containing records is refused.

The methods are rolling out after crm 26.2200.0. The next release version has not been published yet. Until the capability is enabled and the method is available on the account, the response is 422 METHOD_NOT_YET_AVAILABLE with error.release.

NEW-1103-5: Named CRM card layouts

Named CRM card layouts: create, list, read, update, delete, select current, and get the common and personal layout IDs. New /v1/crm/card-layouts/:entityType routes require crm scope, and changes require write access. Layout IDs are strings, while creation returns a numeric ID.

Rolling out: the family was introduced in crm 26.1700.0, and cloud availability also depends on Bitrix24 enabling the capability. Until then the API returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

FIX-1103-6: Long names no longer block bot management

Before

Renaming a bot with a long name could leave the change unconfirmed: Bitrix24 stored a truncated name, blocking subsequent bot operations.

After

POST /v1/bots and PATCH /v1/bots/:botId refuse names exceeding 50 Unicode code points with 400 BOT_NAME_TOO_LONG before registration or an update. Names are never truncated. Updates validate the effective name — in a flat body or in fields.properties.name, including the PROPERTIES and NAME aliases. Supply a shorter name. The owner of a standalone bot whose rename stalled after its name was truncated to 50 Unicode code points can call ordinary DELETE /v1/bots/:botId with the same API key. Vibecode cancels the unfinished rename only after confirming the bot is absent from Bitrix24. If ownership, the key or registration changed, or a previous request may still be in flight, the record is kept and the response is 409. This path does not cover bots linked to AI agents or managed bots.

BC-1103-7: a non-array fm and a multifield keyed by row ids are no longer dropped silently

Old format supported until: not provided

Before

On contacts, leads and companies, a raw fm that is not an array — an object keyed by row ids ({"fm": {"11": {"typeId": "PHONE", "valueType": "WORK", "value": ""}}}), a string, a number, an empty object or an object keyed by type such as PHONE — as well as phone, email or web sent as an object keyed by row ids ({"phone": {"11": {"value": ""}}}) or as any other object without value — empty or with keys such as n0, 0 or 011 — as well as a number, true/false or an array holding such an item ({"phone": [{"11": {…}}]}) was accepted: update (PATCH /v1/contacts/{id}) answered 200, create (POST /v1/contacts) answered 201. Such a value, or inside an array only such an item, was silently discarded and never passed to Bitrix24, while the other fields of the body and the other items of the array were written. Entity batch calls, /v1/batch and import behaved the same way.

After

Such a request is refused before Bitrix24 is called, and nothing is written, including the other fields of the body. An object keyed by row ids in fm, phone, email or web gets 400 MULTIFIELD_ID_NOT_SUPPORTED. A raw fm in any shape other than the array [{ "typeId", "valueType", "value" }], and phone, email or web sent as an object without value, a number, true/false or an array holding such an item, get 400 INVALID_MULTIFIELD_SHAPE. null, an empty array and empty values still change nothing. The check covers single calls, entity batch calls, /v1/batch and import.

What integrators should do

Send fm only as an array [{ "typeId", "valueType", "value" }], and phone, email and web as a string, an array of strings or an array of objects [{ "value", "typeId" }] without an id. If your integration sends such a value together with other fields, or such an item next to valid items of an array, remove it: it was never written itself, and now it makes the whole request fail, including the valid items of the same array that used to be written. Updating or deleting a single multifield row by id through this API is not possible: edit the record in the Bitrix24 interface.

FIX-1103-8: Deal, contact and user read schemas accept unset fields

Before

In /v1/openapi.json, some response fields were declared only as a string, number or date. Successful responses already returned null, for example in a deal's previousStageId and probability, but validation against the published schema rejected them.

After

Read schemas accept null for the following fields:

• Deals: comments, lastCommunicationTime, lastCommunicationCallTime, lastCommunicationEmailTime, lastCommunicationImolTime, lastCommunicationWebformTime, previousStageId, probability, sourceDescription, sourceId.
• Contacts: comments, lastCommunicationTime, lastCommunicationCallTime, lastCommunicationEmailTime, lastCommunicationImolTime, lastCommunicationWebformTime, name, lastName, secondName, post, sourceDescription, typeId.
• Users: lastActivityDate, lastLogin, personalBirthday, timestampX.

Impact on integrators

Response values and write rules are unchanged. After regenerating client models, handle null for these fields. An omitted optional field and a present field containing null remain different cases. The contact name limit of 50 characters is preserved.

Affected endpoints: GET /v1/deals, GET /v1/contacts, GET /v1/users. The same schemas apply to individual record reads and operations that return these records.

NEW-1103-9: connector card: ask and know fields

The GET /v1/connectors/{slug} response gains the ask and know fields — string arrays in the card locale holding ready-made questions for the agent and "good to know" items. They are empty arrays when the card has none. The existing fields and their values are unchanged.

NEW-1103-10: Versioned transcription protocol for chat files

POST /v1/chats/files/:fileId/transcribe accepts the paired optional fields requestId (UUID) and contentVersion (1–128 visible ASCII characters, without spaces). An incomplete or malformed pair is rejected with 400 INVALID_PARAMS; calls without both fields retain their existing request and response format.

GET /v1/chats/transcription/config with the im scope returns only a validated protocol 1 descriptor, without call state or credentials. Both calls require a writing key: reading the underlying configuration can initialize system folders. A read-only key receives 403 WRITE_BLOCKED_READONLY_KEY before any Bitrix24 call. Support depends on Bitrix24; an absent or malformed descriptor returns 422 BITRIX_ERROR with error.b24Code = TRANSCRIPTION_NOT_ACTIVE.

FIX-1103-11: One attempt to start file transcription

Before

POST /v1/chats/files/:fileId/transcribe without the requestId and contentVersion pair could automatically repeat the Bitrix24 call after a refusal or redirect.

After

Starting transcription calls Bitrix24 at most once for either request format. Automatic retries, webhook scope repair and redirect following are disabled. The request and response format is preserved.

Impact on integrators

The API returns the first attempt's error to the calling application. The user starts a new attempt.

FIX-1103-12: CRM tracking and traces lists report an unavailable method

Before: List GET requests in /v1/crm-tracking and /v1/crm-traces returned 500 INTERNAL_ERROR when the REST v3 method was not yet available on the Bitrix24 account.

After: The same requests return 422 METHOD_NOT_YET_AVAILABLE with error.release, as documented.

NEW-1103-13: account hint in the Connect authorization link

GET /v1/connect/authorize accepts an optional portal parameter with the domain of a Bitrix24 account, for example portal=yourcompany.bitrix24.com. If the user is an active member of that account, it is preselected on the consent page. The user can change the selection, and the key is issued for the account the user confirmed. An invalid value causes no error: sign-in proceeds as without the parameter. The authorize response doesn't depend on the parameter. The hint applies to the authorization code flow for clients in PERSONAL mode.