[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-entities\u002Fcrm-search\u002Fsearch":3,"docs-tabs-entities\u002Fcrm-search\u002Fsearch":6},{"content":4,"lastmod":5},"## Search CRM records\n\n`POST \u002Fv1\u002Fcrm\u002Fsearch`\n\nSearches leads, deals, contacts, companies and other CRM records in one request by title, full name, phone or email. Returns at most 20 records across all types combined.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `searchQuery` | string | yes | Search string, not empty and not whitespace only |\n| `options.types` | array | no | CRM types to search: `LEAD`, `DEAL`, `CONTACT`, `COMPANY`, `INVOICE`, `QUOTE`, `SMART_INVOICE`, or a smart process `entityTypeId` as a number from [`GET \u002Fv1\u002Fsmart-processes`](\u002Fdocs\u002Fentities\u002Fsmart-processes\u002Flist). A smart process can also be passed as the string `DYNAMIC_\u003CentityTypeId>`. Without the field, the search covers all of these types |\n| `options.scope` | string | no | Where to search: `DENOMINATION` — title and full name, `INDEX` — full-text index including phone and email. Without the field, the search covers title and full name, and a phone or email query returns an empty `data` array |\n| `options.categoryId` | number | no | Integer. Does not narrow deal results by pipeline: with the `categoryId` of a pipeline from [`GET \u002Fv1\u002Fdeal-categories`](\u002Fdocs\u002Fentities\u002Fdeal-categories\u002Flist), the same records come back as without it |\n\nThe body and `options` accept no other fields: an unknown field is rejected with `400 INVALID_PARAMS`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"searchQuery\": \"+12025550123\",\n    \"options\": { \"scope\": \"INDEX\" }\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"searchQuery\": \"+12025550123\",\n    \"options\": { \"scope\": \"INDEX\" }\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    searchQuery: '+12025550123',\n    options: { scope: 'INDEX' },\n  }),\n})\n\nconst { data, meta } = await res.json()\nfor (const item of data) console.log(item.type, item.id, item.title)\nif (meta.limits.length) console.log('Excluded by plan:', meta.limits.map((l) => l.type))\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fcrm\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    searchQuery: '+12025550123',\n    options: { scope: 'INDEX' },\n  }),\n})\n\nconst { data, meta } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | `true` on success |\n| `data` | array | Records found, at most 20 across all types combined |\n| `data[].id` | number | Record ID |\n| `data[].type` | string | Record type, for example `LEAD`, `DEAL`, `CONTACT`, `COMPANY` |\n| `data[].entityTypeId` | number | Numeric record type, for example `1` — lead, `2` — deal, `3` — contact, `4` — company |\n| `data[].title` | string | Record title or full name |\n| `data[].subTitle` | string | Additional line, for example the contact name on a lead. Can be empty |\n| `data[].links.show` | string \\| null | Path to the record card in the Bitrix24 web interface, relative to the Bitrix24 account address, for example `\u002Fcrm\u002Fcontact\u002Fdetails\u002F3167\u002F`. Not an API endpoint |\n| `data[].attributes.phone` | array | Record phone numbers, items `{ type, value }`. The field is absent if there are no phone numbers |\n| `data[].attributes.email` | array | Record emails, items `{ type, value }`. The field is absent if there are no emails |\n| `meta.limit` | number | Maximum number of records in the response, always `20` |\n| `meta.limits` | array | Types excluded from the search by a Bitrix24 plan limit. Items `{ type, title, description }`. An empty array means no exclusions |\n| `meta.limitsMeaning` | string | Explanation of `meta.limits` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 3167,\n      \"type\": \"CONTACT\",\n      \"entityTypeId\": 3,\n      \"title\": \"Anna Smith\",\n      \"subTitle\": \"\",\n      \"links\": {\n        \"show\": \"\u002Fcrm\u002Fcontact\u002Fdetails\u002F3167\u002F\"\n      },\n      \"attributes\": {\n        \"phone\": [\n          { \"type\": \"WORK\", \"value\": \"+12025550123\" }\n        ],\n        \"email\": [\n          { \"type\": \"WORK\", \"value\": \"anna.smith@example.com\" }\n        ]\n      }\n    }\n  ],\n  \"meta\": {\n    \"limit\": 20,\n    \"limits\": [],\n    \"limitsMeaning\": \"These CRM types were omitted because the Bitrix24 search tariff limit was exceeded\"\n  }\n}\n```\n\n## Error response example\n\n400 — unknown type in `options.types`:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"Unknown CRM type\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `MISSING_REQUIRED_FIELDS` | `searchQuery` is not passed, is not a string, or is whitespace only |\n| 400 | `INVALID_PARAMS` | Unknown type in `options.types`, including a smart process `entityTypeId` that does not exist on the portal. Checked before the search |\n| 400 | `INVALID_PARAMS` | `options.scope` is neither `DENOMINATION` nor `INDEX`, `options.categoryId` is not an integer, `options.types` is not an array |\n| 400 | `INVALID_PARAMS` | Unknown field in the body or in `options`, or the body or `options` is not a JSON object |\n| 502 | `BITRIX_RESPONSE_INVALID` | Bitrix24 returned a search response of an unexpected shape |\n| 403 | `SCOPE_DENIED` | The key has no `crm` scope |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 connection |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**The 20 slots are shared between types.** A short query without `options.types` can return 20 leads and no contacts. To find a customer, pass `types: [\"CONTACT\", \"COMPANY\"]`.\n\n**An empty `data` with a non-empty `meta.limits` does not mean there are no records.** Records of the types in `meta.limits` did not make it into the response. Find them with the list method of the relevant entity, for example [`GET \u002Fv1\u002Fcontacts`](\u002Fdocs\u002Fentities\u002Fcontacts\u002Flist) with a filter.\n\n## See also\n\n- [Get a contact](\u002Fdocs\u002Fentities\u002Fcontacts\u002Fget)\n- [Get a company](\u002Fdocs\u002Fentities\u002Fcompanies\u002Fget)\n- [Smart process types](\u002Fdocs\u002Fentities\u002Fsmart-processes)\n- [CRM search](..\u002Fcrm-search.md)\n","2026-10-15",{},1794739358641]