For AI agents: markdown of this page — /docs-content-en/crm-api-modes.md documentation index — /llms.txt

CRM API modes

The CRM routes of the Vibecode API work in one of two modes: through the previous version of the Bitrix24 REST API (v2) or through the new one (v3). Route paths and field names are the same in both modes; only the data source differs.

Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key | Mode header: X-Crm-Api

What to know first

  1. The mode is stored on the key. While v3 mode does not cover every CRM entity, new keys are created in v2 mode. The mode in which a Bitrix24 account issues new keys is shown by the newKeyMode field of the key self-description. A key in v2 mode behaves the same as before the modes existed. A key issued to replace an active key inherits that key's mode. A Cowork key issued after the previous one was revoked, or for an additional device, takes the mode of the same person's latest Cowork key.
  2. The header overrides the key mode. A request with the X-Crm-Api: v2 or X-Crm-Api: v3 header runs in the given mode; the key mode itself does not change.
  3. The response names the mode. The response of a route that sees the mode carries the X-Crm-Api header with the value v2 or v3 (the mode the request ran in) when the request sent X-Crm-Api itself or the key works in v3 mode. For a key in v2 mode, the response to a request without the X-Crm-Api header is unchanged and carries no such header.
  4. In v3 mode a request never silently falls back to v2. Whatever v3 mode cannot do is refused with 422 CRM_V3_UNSUPPORTED and a hint to repeat the same request with the X-Crm-Api: v2 header. Routes that do not see the mode run through the previous version and respond without the X-Crm-Api header.
  5. v3 mode is available on every Bitrix24 account. It is turned on by the X-Crm-Api: v3 header or by the key mode. If the Bitrix24 account does not have the new version of the Bitrix24 REST API (for example, an on-premise installation with an old REST module), a request in v3 mode gets the same 422 CRM_V3_UNSUPPORTED refusal with a hint to repeat it in v2 mode.

Which routes see the mode

The mode applies to the CRM entity routes: deals, contacts, companies, leads, smart processes, quotes, invoices, activities, requisites, bank details, addresses, pipelines and CRM dictionaries.

Other routes do not see the mode: they respond the same way regardless of the header and do not add the X-Crm-Api header to the response. Among them are currencies, smart process types, automated solutions and the product catalog: the new version of the Bitrix24 REST API has no methods of its own for them. For CRM entities, the main operations see the mode (list, read, create, update, delete, search, aggregation, field descriptions and import), and so do moving a record to another stage and the links between records. Other entity routes do not see the mode and run through the previous version: product rows /v1/{entity}/:id/products, record activities /v1/{entity}/:id/activities and activity actions, lead conversion POST /v1/leads/:id/convert, record files and others. The X-Crm-Api header is not parsed on these routes: no value, not even an invalid one, changes the response, and the header is not added to the response. The absence of this header in the response shows that the previous version handled the request. Moving a record to another stage and the links between records (deal, lead and company contacts, a contact's companies) do see the mode: for a deal they work in v3 mode (see the table below), while for a lead, contact or company they are refused with 422 CRM_V3_UNSUPPORTED. Record import does see the mode: in v3 mode it is refused with 422 CRM_V3_UNSUPPORTED and a hint to repeat the request with the X-Crm-Api: v2 header.

These deal routes work in v3 mode today:

Route How it works in v3 mode
RouteGET /v1/deals How it works in v3 modeFilter, sorting, limit, offset and meta.total. Records are read from Bitrix24 in pages of up to 1000. When the last page read is full, meta.total is counted by a separate request to Bitrix24
RouteGET /v1/deals/:id How it works in v3 modeWithout select, every field that has a counterpart in the new version is returned; with select, only the named fields
RoutePOST /v1/deals/search How it works in v3 modeA date range in the filter is not split into windows: autoWindow has no effect in v3 mode
RoutePOST /v1/deals/aggregate How it works in v3 modeComputes over the records read in v3 mode. Grouping by stageId and stageSemanticId is also computed over the records read, not by a separate count per stage
RouteGET /v1/deals/aggregate How it works in v3 modeComputes the same way as POST /v1/deals/aggregate
RoutePOST /v1/deals How it works in v3 modeCreates a deal. The response is the created deal, read in v3 mode
RoutePATCH /v1/deals/:id How it works in v3 modeUpdates a deal. The response is the updated deal, read in v3 mode
RouteDELETE /v1/deals/:id How it works in v3 modeDeletes a deal
RoutePOST /v1/deals/:id/move How it works in v3 modeMoves a deal to another stage. The response is the deal after the move, read in v3 mode
RouteGET /v1/deals/:id/contacts How it works in v3 modeDeal contacts without sort and roleId. The primary contact is first
RoutePOST /v1/deals/:id/contacts How it works in v3 modeAdds a contact to the end of the list. With isPrimary: true, takes two Bitrix24 calls
RoutePUT /v1/deals/:id/contacts How it works in v3 modeWrites the whole contact list, with the primary contact placed first
RouteDELETE /v1/deals/:id/contacts/:relatedId How it works in v3 modeUnlinks a contact
RouteDELETE /v1/deals/:id/contacts How it works in v3 modeUnlinks all contacts

How deals differ in this mode is described in the v3 mode section of the deals page. Every other operation on the listed entities that sees the mode returns 422 CRM_V3_UNSUPPORTED in v3 mode. Field descriptions from GET /v1/{entity}/fields are returned in v3 mode the same way as in v2 mode.

How the mode is chosen

The request mode comes from the first source that is set:

Order Source Values
Order1 SourceThe X-Crm-Api request header Valuesv2, v3, case-insensitive, surrounding spaces ignored
Order2 SourceThe key mode Valuesv2, v3: the crmApi block in the GET /v1/me response
Order3 SourceDefault Valuesv2

On a route that sees the mode, a header with any other value gets 400 INVALID_PARAMS. Your Vibecode account has no switch for the key mode: the mode is set when the key is created. To work in v3 mode with a key in v2 mode, send the X-Crm-Api: v3 header with every request.

How to find the key mode

The GET /v1/me response for a key bound to a Bitrix24 account contains the data.crmApi block.

Field Type Description
Fieldmode Typestring DescriptionKey mode: v2 or v3
FieldnewKeyMode Typestring DescriptionThe mode new keys are created in on this Bitrix24 account: v2 or v3
Fieldheader Typestring DescriptionName of the header a request uses to choose its mode: X-Crm-Api
Fieldoverride Typestring DescriptionA hint about the header in the key owner's language
JSON
{
  "success": true,
  "data": {
    "crmApi": {
      "mode": "v3",
      "newKeyMode": "v2",
      "header": "X-Crm-Api",
      "override": "X-Crm-Api: v2|v3 — a request header on CRM routes; overrides the key mode."
    }
  }
}

Examples

Request a deal in v3 mode with the header. The JavaScript examples repeat the request in v2 mode if v3 mode refuses it with CRM_V3_UNSUPPORTED: getDeal(7, 'v3').

curl — personal key

Terminal
curl -i "https://vibecode.bitrix24.com/v1/deals/7?select=title,amount,stageId" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Crm-Api: v3"

curl — OAuth app

Terminal
curl -i "https://vibecode.bitrix24.com/v1/deals/7?select=title,amount,stageId" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "X-Crm-Api: v3"

JavaScript — personal key

javascript
async function getDeal(id, mode) {
  const res = await fetch(`https://vibecode.bitrix24.com/v1/deals/${id}?select=title,amount,stageId`, {
    headers: { 'X-Api-Key': 'YOUR_API_KEY', ...(mode ? { 'X-Crm-Api': mode } : {}) },
  })
  const body = await res.json()
  if (res.status === 422 && body.error?.code === 'CRM_V3_UNSUPPORTED') {
    return getDeal(id, body.error.details.retryWith.value)
  }
  console.log('Response mode:', res.headers.get('X-Crm-Api'))
  return body
}

JavaScript — OAuth app

javascript
async function getDeal(id, mode) {
  const res = await fetch(`https://vibecode.bitrix24.com/v1/deals/${id}?select=title,amount,stageId`, {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      ...(mode ? { 'X-Crm-Api': mode } : {}),
    },
  })
  const body = await res.json()
  if (res.status === 422 && body.error?.code === 'CRM_V3_UNSUPPORTED') {
    return getDeal(id, body.error.details.retryWith.value)
  }
  console.log('Response mode:', res.headers.get('X-Crm-Api'))
  return body
}

The CRM_V3_UNSUPPORTED refusal

The refusal comes with status 422. error.message says what exactly v3 mode cannot do. error.details.retryWith names the header and value that make the same request run in v2 mode.

JSON
{
  "success": false,
  "error": {
    "code": "CRM_V3_UNSUPPORTED",
    "message": "Field \"probability\" has no counterpart in Bitrix24 REST v3.",
    "hint": "Repeat the same request with the header X-Crm-Api: v2.",
    "details": {
      "retryWith": { "header": "X-Crm-Api", "value": "v2" }
    }
  }
}

A retry with X-Crm-Api: v2 applies to that request only: subsequent requests run in the key mode again.

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe X-Crm-Api header on a route that sees the mode has a value other than v2 or v3
HTTP422 CodeCRM_V3_UNSUPPORTED DescriptionThe Bitrix24 account does not have the new version of the Bitrix24 REST API, or it has no method for this operation. The response carries X-Crm-Api: v3
HTTP422 CodeCRM_V3_UNSUPPORTED Descriptionv3 mode cannot serve this request: the operation, a field, the form of a value, a filter condition or the sort order. The response carries X-Crm-Api: v3

Other errors in v3 mode come with the same codes as in v2 mode: a missing record is 404 ENTITY_NOT_FOUND, missing permissions are 403 BITRIX_ACCESS_DENIED, an invalid field value is 400. The error text in this mode comes from the response of the new version of the Bitrix24 REST API. Full reference: Error codes.

What the new version of the Bitrix24 REST API cannot do

These requests are refused with 422 CRM_V3_UNSUPPORTED in v3 mode and run only in v2 mode:

  • substring search in a filter,
  • filtering by an empty value on fields other than the reference fields companyId, contactId and mycompanyId,
  • filtering and sorting by multiple-value fields, by the utm* tracking tags, by the last-communication time fields lastCommunication*Time and by custom fields of the types crm, money, file, address, iblock_element and iblock_section,
  • fields that have no counterpart in the new version, in select, filters, sorting and writes (for example, probability and additionalInfo on a deal, isReturnCustomer on a lead),
  • creating and updating activities, and listing activities without an owner,
  • statuses and stages of leads, quotes and invoices.

See also