[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-crm-api-modes":3,"docs-tabs-crm-api-modes":6},{"content":4,"lastmod":5},"# CRM API modes\n\nThe 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.\n\n**Base URL:** `https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1` | **Authorization:** `X-Api-Key` | **Mode header:** `X-Crm-Api`\n\n## What to know first\n\n1. **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](#how-to-find-the-key-mode). 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.\n2. **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.\n3. **The response names the mode.** The response of a route that [sees the mode](#which-routes-see-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.\n4. **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.\n5. **`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.\n\n## Which routes see the mode\n\nThe mode applies to the CRM entity routes: [deals](.\u002Fentities\u002Fdeals.md), [contacts](.\u002Fentities\u002Fcontacts.md), [companies](.\u002Fentities\u002Fcompanies.md), [leads](.\u002Fentities\u002Fleads.md), [smart processes](.\u002Fentities\u002Fitems.md), [quotes](.\u002Fentities\u002Fquotes.md), [invoices](.\u002Fentities\u002Finvoices.md), [activities](.\u002Fentities\u002Factivities.md), [requisites](.\u002Fentities\u002Frequisites.md), [bank details](.\u002Fentities\u002Fbank-details.md), [addresses](.\u002Fentities\u002Faddresses.md), [pipelines](.\u002Fentities\u002Fcategories.md) and [CRM dictionaries](.\u002Fentities\u002Fstatuses.md).\n\nOther 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 `\u002Fv1\u002F{entity}\u002F:id\u002Fproducts`, record activities `\u002Fv1\u002F{entity}\u002F:id\u002Factivities` and activity actions, lead conversion `POST \u002Fv1\u002Fleads\u002F:id\u002Fconvert`, 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.\n\nThese deal routes work in `v3` mode today:\n\n| Route | How it works in `v3` mode |\n|-------|---------------------------|\n| `GET \u002Fv1\u002Fdeals` | Filter, 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 |\n| `GET \u002Fv1\u002Fdeals\u002F:id` | Without `select`, every field that has a counterpart in the new version is returned; with `select`, only the named fields |\n| `POST \u002Fv1\u002Fdeals\u002Fsearch` | A date range in the filter is not split into windows: `autoWindow` has no effect in `v3` mode |\n| `POST \u002Fv1\u002Fdeals\u002Faggregate` | Computes 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 |\n| `GET \u002Fv1\u002Fdeals\u002Faggregate` | Computes the same way as `POST \u002Fv1\u002Fdeals\u002Faggregate` |\n| `POST \u002Fv1\u002Fdeals` | Creates a deal. The response is the created deal, read in `v3` mode |\n| `PATCH \u002Fv1\u002Fdeals\u002F:id` | Updates a deal. The response is the updated deal, read in `v3` mode |\n| `DELETE \u002Fv1\u002Fdeals\u002F:id` | Deletes a deal |\n| `POST \u002Fv1\u002Fdeals\u002F:id\u002Fmove` | Moves a deal to another stage. The response is the deal after the move, read in `v3` mode |\n| `GET \u002Fv1\u002Fdeals\u002F:id\u002Fcontacts` | Deal contacts without `sort` and `roleId`. The primary contact is first |\n| `POST \u002Fv1\u002Fdeals\u002F:id\u002Fcontacts` | Adds a contact to the end of the list. With `isPrimary: true`, takes two Bitrix24 calls |\n| `PUT \u002Fv1\u002Fdeals\u002F:id\u002Fcontacts` | Writes the whole contact list, with the primary contact placed first |\n| `DELETE \u002Fv1\u002Fdeals\u002F:id\u002Fcontacts\u002F:relatedId` | Unlinks a contact |\n| `DELETE \u002Fv1\u002Fdeals\u002F:id\u002Fcontacts` | Unlinks all contacts |\n\nHow deals differ in this mode is described in the [v3 mode](.\u002Fentities\u002Fdeals.md#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 \u002Fv1\u002F{entity}\u002Ffields` are returned in `v3` mode the same way as in `v2` mode.\n\n## How the mode is chosen\n\nThe request mode comes from the first source that is set:\n\n| Order | Source | Values |\n|-------|--------|--------|\n| 1 | The `X-Crm-Api` request header | `v2`, `v3`, case-insensitive, surrounding spaces ignored |\n| 2 | The key mode | `v2`, `v3`: the `crmApi` block in the `GET \u002Fv1\u002Fme` response |\n| 3 | Default | `v2` |\n\nOn 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.\n\n## How to find the key mode\n\nThe `GET \u002Fv1\u002Fme` response for a key bound to a Bitrix24 account contains the `data.crmApi` block.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `mode` | string | Key mode: `v2` or `v3` |\n| `newKeyMode` | string | The mode new keys are created in on this Bitrix24 account: `v2` or `v3` |\n| `header` | string | Name of the header a request uses to choose its mode: `X-Crm-Api` |\n| `override` | string | A hint about the header in the key owner's language |\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"crmApi\": {\n      \"mode\": \"v3\",\n      \"newKeyMode\": \"v2\",\n      \"header\": \"X-Crm-Api\",\n      \"override\": \"X-Crm-Api: v2|v3 — a request header on CRM routes; overrides the key mode.\"\n    }\n  }\n}\n```\n\n## Examples\n\nRequest 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')`.\n\n### curl — personal key\n\n```bash\ncurl -i \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F7?select=title,amount,stageId\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"X-Crm-Api: v3\"\n```\n\n### curl — OAuth app\n\n```bash\ncurl -i \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F7?select=title,amount,stageId\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"X-Crm-Api: v3\"\n```\n\n### JavaScript — personal key\n\n```javascript\nasync function getDeal(id, mode) {\n  const res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F${id}?select=title,amount,stageId`, {\n    headers: { 'X-Api-Key': 'YOUR_API_KEY', ...(mode ? { 'X-Crm-Api': mode } : {}) },\n  })\n  const body = await res.json()\n  if (res.status === 422 && body.error?.code === 'CRM_V3_UNSUPPORTED') {\n    return getDeal(id, body.error.details.retryWith.value)\n  }\n  console.log('Response mode:', res.headers.get('X-Crm-Api'))\n  return body\n}\n```\n\n### JavaScript — OAuth app\n\n```javascript\nasync function getDeal(id, mode) {\n  const res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fdeals\u002F${id}?select=title,amount,stageId`, {\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n      ...(mode ? { 'X-Crm-Api': mode } : {}),\n    },\n  })\n  const body = await res.json()\n  if (res.status === 422 && body.error?.code === 'CRM_V3_UNSUPPORTED') {\n    return getDeal(id, body.error.details.retryWith.value)\n  }\n  console.log('Response mode:', res.headers.get('X-Crm-Api'))\n  return body\n}\n```\n\n## The CRM_V3_UNSUPPORTED refusal\n\nThe 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.\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"CRM_V3_UNSUPPORTED\",\n    \"message\": \"Field \\\"probability\\\" has no counterpart in Bitrix24 REST v3.\",\n    \"hint\": \"Repeat the same request with the header X-Crm-Api: v2.\",\n    \"details\": {\n      \"retryWith\": { \"header\": \"X-Crm-Api\", \"value\": \"v2\" }\n    }\n  }\n}\n```\n\nA retry with `X-Crm-Api: v2` applies to that request only: subsequent requests run in the key mode again.\n\n## Errors\n\n| HTTP | Code | Description |\n|------|------|-------------|\n| 400 | `INVALID_PARAMS` | The `X-Crm-Api` header on a route that sees the mode has a value other than `v2` or `v3` |\n| 422 | `CRM_V3_UNSUPPORTED` | The 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` |\n| 422 | `CRM_V3_UNSUPPORTED` | `v3` 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` |\n\nOther 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](.\u002Ferrors.md).\n\n## What the new version of the Bitrix24 REST API cannot do\n\nThese requests are refused with `422 CRM_V3_UNSUPPORTED` in `v3` mode and run only in `v2` mode:\n\n- substring search in a filter,\n- filtering by an empty value on fields other than the reference fields `companyId`, `contactId` and `mycompanyId`,\n- 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`,\n- 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),\n- creating and updating activities, and listing activities without an owner,\n- statuses and stages of leads, quotes and invoices.\n\n## See also\n\n- [Key self-description](.\u002Fkeys-auth\u002Fme.md)\n- [Deals](.\u002Fentities\u002Fdeals.md): the v3 mode section\n- [List deals](.\u002Fentities\u002Fdeals\u002Flist.md)\n- [Search deals](.\u002Fentities\u002Fdeals\u002Fsearch.md)\n- [Aggregate deals](.\u002Fentities\u002Fdeals\u002Faggregate.md)\n- [Recurring deals](.\u002Fentities\u002Frecurring-deals.md)\n- [Filtering syntax](.\u002Ffiltering.md)\n- [Error codes](.\u002Ferrors.md)\n","2026-11-18",{},1795000247093]