Для AI-агентов: markdown этой страницы — /docs-content/entities/contacts/search.md индекс документации — /llms.txt

Поиск контактов

POST /v1/contacts/search

Поиск контактов по условиям в теле запроса. Принимает те же фильтры, что и список контактов, и рассчитан на составные условия и большие выборки.

Поля запроса (body)

Параметр Тип По умолч. Описание
filter object — Фильтрация по полям GET /v1/contacts/fields.
Синтаксис фильтрации. Пример: { "companyId": 15 }
limit number 50 Количество записей (до 5000)
offset number 0 Пропустить N записей. Вместе с фильтром по диапазону дат шире 14 дней отклоняется — см. UNSTABLE_OFFSET_PAGINATION в разделе «Ошибки»
order object — Сортировка: { "lastName": "asc" }
select string[] — Выборка полей: ["id", "name", "lastName", "phone"]

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/contacts/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "companyId": 15 },
    "limit": 10,
    "order": { "lastName": "asc" }
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/contacts/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "companyId": 15 },
    "limit": 10,
    "order": { "lastName": "asc" }
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/contacts/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { companyId: 15 },
    limit: 10,
    order: { lastName: 'asc' },
  }),
})

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

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/contacts/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { companyId: 15 },
    limit: 10,
    order: { lastName: 'asc' },
  }),
})

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

Поля ответа

Поле Тип Описание
data array Массив контактов (поля — см. Поля)
meta.total number Сколько записей подошло под фильтр
meta.hasMore boolean Есть ли следующая страница
meta.nextAfterId string Идентификатор последней отданной записи. Приходит при сортировке строго по id по возрастанию, пока hasMore равен true. Передайте его обратно в фильтр >id — это дешёвая замена растущему offset
meta.durationMs number Длительность запроса в миллисекундах

Поля meta лежат рядом с data, а не внутри него. Обходить страницы нужно по meta.hasMore: длина data, равная limit, последней страницы не исключает.

URL карточки любого контакта из массива data — его id:

https://<portal>.bitrix24.ru/crm/contact/details/<id>/

<portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "id": 71,
      "name": "Иван",
      "lastName": "Петров",
      "phone": "74955553546",
      "companyId": 15,
      "assignedById": 1,
      "typeId": "CLIENT"
    }
  ]
}

Пример ответа при ошибке

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Ошибки

HTTP Код Описание
400 UNSTABLE_OFFSET_PAGINATION offset больше нуля вместе с фильтром по диапазону дат шире 14 дней. Два разных алгоритма выдачи дают несогласованные результаты, поэтому запрос отклоняется. Возьмите всё одним запросом с limit до 5000, либо передайте autoWindow: false с сортировкой по id, либо режьте диапазон дат на части сами
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Фильтр по телефону подходит не для всякого поиска. Значение без оператора сравнивается со всей сохранённой строкой: контакт с номером +7 (999) 123-45-67 найдётся по этой же строке и не найдётся по 79991234567, потому что плюс, пробелы, скобки и дефисы — часть значения. Вдобавок фильтр видит только первый номер записи: если записаны рабочий и мобильный, по мобильному он вернёт пустой список. Чтобы найти контакт по номеру телефона в любом написании и по любому из его номеров, используйте Поиск дубликатов. Оператор $contains при этом работает — он ищет кусок текста внутри значения, это рабочий способ для почты: { "email": { "$contains": "@example.com" } }.

Смотрите также