CRM search

Find a client or a deal across several CRM types in one request: by title, full name, phone or email.

Bitrix24 API: crm.entity.search Scope: crm

Search CRM records

POST /v1/crm/search

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

Request fields (body)

Field	Type	Required	Description
Field`searchQuery`	Typestring	Requiredyes	DescriptionSearch string, not empty and not whitespace only
Field`options.types`	Typearray	Requiredno	DescriptionCRM types to search: `LEAD`, `DEAL`, `CONTACT`, `COMPANY`, `INVOICE`, `QUOTE`, `SMART_INVOICE`, or a smart process `entityTypeId` as a number from `GET /v1/smart-processes`. A smart process can also be passed as the string `DYNAMIC_<entityTypeId>`. Without the field, the search covers all of these types
Field`options.scope`	Typestring	Requiredno	DescriptionWhere 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
Field`options.categoryId`	Typenumber	Requiredno	DescriptionInteger. Does not narrow deal results by pipeline: with the `categoryId` of a pipeline from `GET /v1/deal-categories`, the same records come back as without it

The body and options accept no other fields: an unknown field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/crm/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQuery": "+12025550123",
    "options": { "scope": "INDEX" }
  }'

curl — OAuth application

Terminal

curl -X POST "https://vibecode.bitrix24.com/v1/crm/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQuery": "+12025550123",
    "options": { "scope": "INDEX" }
  }'

JavaScript — personal key

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/crm/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    searchQuery: '+12025550123',
    options: { scope: 'INDEX' },
  }),
})

const { data, meta } = await res.json()
for (const item of data) console.log(item.type, item.id, item.title)
if (meta.limits.length) console.log('Excluded by plan:', meta.limits.map((l) => l.type))

JavaScript — OAuth application

javascript

const res = await fetch('https://vibecode.bitrix24.com/v1/crm/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    searchQuery: '+12025550123',
    options: { scope: 'INDEX' },
  }),
})

const { data, meta } = await res.json()

Response fields

Field	Type	Description
Field`success`	Typeboolean	Description`true` on success
Field`data`	Typearray	DescriptionRecords found, at most 20 across all types combined
Field`data[].id`	Typenumber	DescriptionRecord ID
Field`data[].type`	Typestring	DescriptionRecord type, for example `LEAD`, `DEAL`, `CONTACT`, `COMPANY`
Field`data[].entityTypeId`	Typenumber	DescriptionNumeric record type, for example `1` — lead, `2` — deal, `3` — contact, `4` — company
Field`data[].title`	Typestring	DescriptionRecord title or full name
Field`data[].subTitle`	Typestring	DescriptionAdditional line, for example the contact name on a lead. Can be empty
Field`data[].links.show`	Typestring \| null	DescriptionPath to the record card in the Bitrix24 web interface, relative to the Bitrix24 account address, for example `/crm/contact/details/3167/`. Not an API endpoint
Field`data[].attributes.phone`	Typearray	DescriptionRecord phone numbers, items `{ type, value }`. The field is absent if there are no phone numbers
Field`data[].attributes.email`	Typearray	DescriptionRecord emails, items `{ type, value }`. The field is absent if there are no emails
Field`meta.limit`	Typenumber	DescriptionMaximum number of records in the response, always `20`
Field`meta.limits`	Typearray	DescriptionTypes excluded from the search by a Bitrix24 plan limit. Items `{ type, title, description }`. An empty array means no exclusions
Field`meta.limitsMeaning`	Typestring	DescriptionExplanation of `meta.limits`

Response example

JSON

{
  "success": true,
  "data": [
    {
      "id": 3167,
      "type": "CONTACT",
      "entityTypeId": 3,
      "title": "Anna Smith",
      "subTitle": "",
      "links": {
        "show": "/crm/contact/details/3167/"
      },
      "attributes": {
        "phone": [
          { "type": "WORK", "value": "+12025550123" }
        ],
        "email": [
          { "type": "WORK", "value": "anna.smith@example.com" }
        ]
      }
    }
  ],
  "meta": {
    "limit": 20,
    "limits": [],
    "limitsMeaning": "These CRM types were omitted because the Bitrix24 search tariff limit was exceeded"
  }
}

Error response example

400 — unknown type in options.types: