# 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`

## Operations

- [Search CRM records](./crm-search/search.md) — `POST /v1/crm/search`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `searchQuery` | string | Search string |
| `options.types` | array | CRM types to search: `LEAD`, `DEAL`, `CONTACT`, `COMPANY`, `INVOICE`, `QUOTE`, `SMART_INVOICE` or a smart process `entityTypeId` as a number from [`GET /v1/smart-processes`](/docs/entities/smart-processes/list) |
| `options.scope` | string | Where to search: `DENOMINATION` — title and full name, `INDEX` — full-text index including phone and email |
| `data[].type`, `data[].id` | string, number | Type and ID of the found record. Use them to read the record through its own section, for example [`GET /v1/contacts/:id`](/docs/entities/contacts/get) |
| `meta.limits` | array | Types excluded from the search by a Bitrix24 plan restriction |

## Before you start

1. **At most 20 records across all types combined, no pagination.** A broad query without `options.types` can fill all 20 slots with records of a single type. To find a contact or a company, pass `types`.
2. **Phone and email are searched only with `scope: "INDEX"`.** Without `scope` the search covers title and full name, and a query by phone number returns an empty list.
3. **An empty `data` does not mean there are no records.** If `meta.limits` is not empty, the types it lists are excluded by a Bitrix24 plan restriction, and their records are not in the response.
4. **A read-only key is enough.** The search changes nothing on the Bitrix24 account.

## Typical scenario

1. Find a client by phone: [`POST /v1/crm/search`](./crm-search/search.md) with `searchQuery` and `options.scope: "INDEX"`.
2. Check `meta.limits`: if it is not empty, some types were left out of the search.
3. Read the found record by `type` and `id`, for example [`GET /v1/contacts/:id`](/docs/entities/contacts/get).
4. Create a to-do for the found client: [`POST /v1/activity-todos`](/docs/entities/activities/todos/create).

## Limits

| Limit | Value |
|-------|----------|
| Records per response | at most 20 across all types combined |
| Pagination | none |
| Batch calls | not supported: [`POST /v1/batch`](/docs/batch) returns `UNKNOWN_ENTITY` for `crm-search`, call the search as a separate request |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Contacts](./contacts.md)
- [Companies](./companies.md)
- [Leads](./leads.md)
- [Deals](./deals.md)
- [Entity reference](/docs/entity-api)