Читать 17

Выгрузка данных по клиентам


Описание

Метод позволяет выгружать подробные данные по клиентам из Calltouch. Это полезно, когда вы хотите получить информацию о ваших клиентах, включая их контакты, историю взаимодействий, теги, менеджеров, пользовательские поля и другие данные для обработки и анализа во внешних системах.

Как работает метод

Метод выполняет поиск клиентов по одному из трёх критериев: по ID клиента, по контактам (телефон, email, VK, Telegram, WhatsApp) или по временному периоду. После поиска метод возвращает полную информацию по найденным клиентам, включая цепочку всех их взаимодействий.

Данные выгружаются постранично - в одном ответе можно получить до 100 клиентов на странице.

Какие данные можно выгружать

Метод позволяет получить полный профиль клиента:

  • Контакты — ФИО, телефоны, email, контакты в мессенджерах.
  • Цепочка взаимодействий — полная история всех касаний клиента, упорядоченная по датам (до 500 взаимодействий). Для каждого взаимодействия отдаются дата, тип и источники.
  • Теги — теги из взаимодействий и теги, назначенные клиенту.
  • Менеджеры — менеджеры, обработавшие взаимодействия, и менеджеры клиента.
  • Пользовательские поля — пользовательские поля из взаимодействий и пользовательские поля, назначенные клиенту.
  • Выручка (LTV) клиента — общий доход, связанный с клиентом.
  • Истории импортов — данные, которые были загружены в профиль клиента через метод импорта.

Какие конкретно параметры отдаёт API — см. раздел "Параметры ответа".

API-метод для выгрузки данных по клиентам

Запрос

POST: 

https://api.calltouch.ru/clients-service/v1/api/client/list

HTTP-заголовки:

  • Access-Token — API-ключ
  • SiteId — ID ЛК Calltouch

Тело запроса в формате JSON.

Пример тела запроса

{
    "clientIds": ["f19e7a17-e913-4b4d-a14c-e3e31d08352d"],
    "clientContacts": {
        "phoneNumbers": ["79000000000","79000000001"],
        "emails": ["mail1@mail.ru","mail2@mail.ru"],
        "vkIds": ["12345"],
        "tgUsernames": ["testuser"],
        "waPhoneNumbers": ["79000000000"]
    },
    "listByDate": {
        "dateFrom": "2025-12-22",
        "dateTo": "2025-12-23",
        "viewType": "firstInteraction"
    },
    "withInteractionChainSources": true,
    "attribution": 1,
    "withTags": true,
    "withManagers": true,
    "withCustomFields": true,
    "withImports": true,
    "withCtCookiesDuplicates": true,
    "limit": 100,
    "page": 1
}

Параметры запроса

Параметр Формат Обязательный Описание
clientIds array

Обязательно должен быть указан один из параметров:

  • clientIds
  • clientContacts
  • listByDate

ID клиентов внутри Calltouch.

Ограничения: максимум 100 ID за один запрос. 
clientContacts object

Обязательно должен быть указан один из параметров:

  • clientIds
  • clientContacts
  • listByDate
 Объект с параметрами выгрузки клиентов по их контактам.   
clientContacts.
phoneNumbers 		array 

Если указан clientContacts: обязательно должен быть указан один из параметров:

  • phoneNumbers;
  • emails;
  • vkIds;
  • tgUsernames;
  • waPhoneNumbers.
Может быть указано несколько параметров.         

Номера телефонов клиентов.

Номера могут быть в любом формате (71234567890, +71234567890, 8 (123) 456-78-90 и т.д.)

Ограничения: максимум 100 номеров за один запрос. 

clientContacts.

emails  		array Email-ы клиентов. 

Формат: xxx@domen.xx

Ограничения: максимум 100 почт за один запрос.

clientContacts.

vkIds  		array

ID ВКонтакте клиентов.

Ограничения: максимум 100 ID за один запрос. 

clientContacts.

tgUsernames  		array

Telegram Username клиентов.

Ограничения: максимум 100 username за один запрос. 

clientContacts.

waPhoneNumbers  		array

Номера телефонов клиентов из Whatsapp. Массив, можно перечислить до 100 штук. 

Номера могут быть в любом формате (71234567890, +71234567890, 8 (123) 456-78-90 и т.д.)

Ограничения: максимум 100 номеров за один запрос. 

listByDate  object 

Обязательно должен быть указан один из параметров:

  • clientIds
  • clientContacts
  • listByDate
 Объект с параметрами выгрузки клиентов по временному периоду. 
listByDate.
dateFrom  		string  Если указан listByDate: обязательно должны быть указаны оба параметра: dateFrom и dateTo 

Дата и время начала выборки.

Формат: "yyyy-mm-dd" или "yyyy-mm-dd HH:MM:SS" 

listByDate.
dateTo  		string  Если указан listByDate: обязательно должны быть указаны оба параметра: dateFrom и dateTo 

Дата и время конца выборки.

Формат: "yyyy-mm-dd" или "yyyy-mm-dd HH:MM:SS" 

listByDate.
viewType  		string  Нет 

Тип выборки клиентов по датам.

Определяет, по какой дате фильтровать клиентов в указанном периоде (dateFrom и dateTo).

Возможные значения:

  • firstInteraction — по дате первого взаимодействия. В выгрузку попадают клиенты, у которых первое взаимодействие произошло в указанный период (по умолчанию).
  • lastInteraction — по дате последнего взаимодействия. В выгрузку попадают клиенты, у которых последнее взаимодействие произошло в указанный период.
  • anyIteraction — по дате любого из взаимодействий. В выгрузку попадают все клиенты, у которых есть хотя бы одно взаимодействие в указанный период.
Если параметр не указан, применяется значение по умолчанию — firstInteraction. 
withInteractionChainSources  boolean  Нет 

Флаг вывода источников взаимодействий (source, medium, campaign, content, keyword) в цепочке взаимодействий клиента.

По умолчанию false.

Источники отдаются по выбранной в параметре attribution модели атрибуции.   
attribution  integer Нет 

Модель атрибуции для выгрузки источников.

Возможные значения:

  • 0 — последнее взаимодействие;
  • 1 — последний непрямой (по умолчанию, если параметр не указан).
withTags  boolean Нет 

Флаг выгрузки тегов.

  • true — выгружать;
  • false — не выгружать.
По умолчанию false.   
withManagers  boolean  Нет 

Флаг выгрузки менеджеров.

  • true — выгружать;
  • false — не выгружать.
По умолчанию false.   
withCustomFields  boolean  Нет 

Флаг выгрузки пользовательских полей.

  • true — выгружать;
  • false — не выгружать.
По умолчанию false.   
withImports  boolean  Нет 

Флаг выгрузки данных, которые были загружены в профиль клиента через метод импорта.

  • true — выгружать;
  • false — не выгружать.
По умолчанию false.   
withCtCookiesDuplicates  boolean  Нет 

Флаг выгрузки кук клиента, которые не учитываются при построении цепочки взаимодействий.

  • true — выгружать;
  • false — не выгружать.
По умолчанию false.   
limit  integer  Обязательный 

Сколько клиентов выводить на одной странице.

Ограничения: максимум 100 клиентов. 
page  integer  Обязательный  Номер страницы для постраничной выгрузки. 

Ответ

Выгрузка данных выполняется сразу и возвращает результат с информацией по найденным клиентам.

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

{
  "meta": [],
  "data": {
    "page": 1,
    "pageTotal": 1,
    "pageSize": 100,
    "clientsTotal": 1,
    "clients": [
        // клиент 1
      {
        "clientId": "f19e7a17-e913-4b4d-a14c-e3e31d08352d",
        "firstInteractionDate": "2024-05-07 09:10:43",
        "lastInteractionDate": "2025-12-22 21:30:00",
        "clientContacts": {
          "mainContacts": {
            "fio": "Вася Васин",
            "phoneNumber": "79996665544",
            "email": "test1@test.ru",
            "vkId": "1234567",
            "tgUsername": "kirpich",
            "waPhoneNumber": "79000000000"
          },
          "otherContacts": {
            "fio": ["Вася Кирпич"],
            "phoneNumber": ["79999191124","79999191125"],
            "email": ["test3@test.ru","test4@test.ru"],
            "vkId": ["7654321"],
            "tgUsername": ["kirpich2"],
            "waPhoneNumber": ["79111111112"]
          }
        },
        "interactionsChain": [
          {
            "date": "2025-12-22 21:30:00",
            "type": "call",
            "id": 12345,
            "medium": "cpc",
            "source": "yandex",
            "campaign": "RSA",
            "keyword": "test",
            "content": "123234"
          }
        ],
        "interactions": {
          "call": 1
        },
        "ctCookies": ["12345678910"],
        "ctCookiesDuplicates": ["12345678911"],
        "tags": {
          "interactionsTags": [
            {"type": "AUTO-PN","name": "Целевой"},
            {"type": "CTLEADS","name": "Клиент проходил через триггерный сценарий"}
          ],
          "clientTags": [
            {"type": "MANUAL","name": "Тег1"}
          ]
        },
        "managers": {
          "interactionsManagers": ["Менеджер 1","Менеджер 2"],
          "clientManagers": ["Менеджер 3"]
        },
        "customFields": {
          "interactionsCustomFields": [
            {"field": "model","value": "Калина"},
            {"field": "brand","value": "Лада"}
          ],
          "clientCustomFields": [
            {"field": "rating","value": 8},
            {"field": "birthday","value": "01-01-1991"}
          ]
        },
        "ltv": 123,
        "ltvCurrencyCode": "RUB",
        "imports": [
          {
            "importLogId": 6370,
            "externalClientId": "123321",
            "clientContacts": {
              "mainContacts": {
                "fio": "Петр Первый",
                "phoneNumber": "79000000011",
                "email": "test20@test.ru",
                "vkId": "12345",
                "tgId": "12345",
                "tgUsername": "testuser123",
                "waPhoneNumber": "79000000012"
              },
              "otherContacts": {
                "fio": [],
                "phoneNumber": ["79000000013","79000000014"],
                "email": ["test21@test.ru","test31@test.ru"],
                "vkId": ["123456"],
                "tgId": ["123456"],
                "tgUsername": ["testuser231"],
                "waPhoneNumber": ["79000000015"]
              }
            },
            "tags": ["Тег1","Тег2"],
            "managers": ["Менеджер1","Менеджер2"],
            "customFields": [
              {"field": "data_test","value": "01-01-2025"},
              {"field": "source","value": "lada"},
              {"field": "test_num","value": "123"}
            ],
            "sessionsInfo": {
              "sessionId": ["1234567"],
              "ctClientId": ["10111213"],
              "ctGlobalId": null,
              "gaClientId": ["10111212314"],
              "yaClientId": ["1415161718192025"]
            },
            "comment": {
              "text": "Комментарий"
            }
          }
        ]
      },   
    // клиент 2
    ...
    ]
  }
}

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

Параметр Формат Описание
data.page integer

Текущая страница выгрузки.

data.pageTotal integer Всего страниц в выгрузке.
data.pageSize integer Лимит количества клиентов на одной странице.
data.clientsTotal integer Количество клиентов на текущей странице.
data.clients array Массив с клиентами.
data.clients[n].
clientId 		string ID клиента внутри Calltouch.
data.clients[n].
firstInteractionDate 		string

Дата и время первого взаимодействия.

Формат: "yyyy-mm-dd hh:mm:ss"

data.clients[n].
lastInteractionDate 		string

Дата и время последнего взаимодействия.

Формат: "yyyy-mm-dd hh:mm:ss"

data.clients[n].
clientContacts 		object Объект с контактами клиента.
data.clients[n].
clientContacts.
mainContacts 		object Основные контакты клиента.
data.clients[n].
clientContacts.
mainContacts.
fio 		string Основное ФИО клиента.
data.clients[n].
clientContacts.
mainContacts.
phoneNumber 		string Основной номер телефона клиента.
data.clients[n].
clientContacts.
mainContacts.
email 		string Основной email клиента.
data.clients[n].
clientContacts.
mainContacts.
vkId 		string Основной ID ВКонтакте клиента.
data.clients[n].
clientContacts.
mainContacts.
tgId 		string Основной ID Telegram клиента.
data.clients[n].
clientContacts.
mainContacts.
tgUsername 		string Основной Telegram Username клиента.
data.clients[n].
clientContacts.
mainContacts.
waPhoneNumber 		string Основной номер телефона клиента в Whatsapp.
data.clients[n].
clientContacts.
otherContacts 		object Дополнительные контакты клиента.
data.clients[n].
clientContacts.
otherContacts.
fio 		array Дополнительные ФИО клиента.
data.clients[n].
clientContacts.
otherContacts.
phoneNumber 		array Дополнительные номера телефона клиента.
data.clients[n].
clientContacts.
otherContacts.
email 		array Дополнительные email клиента.
data.clients[n].
clientContacts.
otherContacts.
vkId 		array Дополнительные ID ВКонтакте клиента.
data.clients[n].
clientContacts.
otherContacts.
tgId 		array Дополнительные ID Telegram клиента.
data.clients[n].
clientContacts.
otherContacts.
tgUsername 		array Дополнительные Telegram Username клиента.
data.clients[n].
clientContacts.
otherContacts.
waPhoneNumber 		array Дополнительные номера телефона клиента в Whatsapp.
data.clients[n].
interactionsChain 		array

Цепочка взаимодействий клиента.

Объекты взаимодействий из цепочки упорядочены по дате взаимодействия, от самого первого взаимодействия до самого последнего.

Ограничения: отдаётся максимум 500 взаимодействий.

data.clients[n].
interactionsChain[n].
date 		string

Дата взаимодействия.

Формат: "yyyy-mm-dd hh:mm:ss"

data.clients[n].
interactionsChain[n].
type 		string

Тип взаимодействия.

Возможные значения:

  • call — звонок;
  • request — заявка;
  • order — сделка;
  • chat — чат;
  • session — сессия;
  • goal — цель;
  • ecommerce — событие е-комма;
  • scenario — событие срабатывания смарт-коммуникации.
data.clients[n].
interactionsChain[n].
id 		string ID взаимодействия внутри Calltouch.
data.clients[n].
interactionsChain[n].
source 		string

Источник.

Отдаётся только если withInteractionChainSources=true.

data.clients[n].
interactionsChain[n].
medium 		string

Канал.

Отдаётся только если withInteractionChainSources=true.

data.clients[n].
interactionsChain[n].
campaign 		string

Кампания.

Отдаётся только если withInteractionChainSources=true.

data.clients[n].
interactionsChain[n].
content 		string

Объявление.

Отдаётся только если withInteractionChainSources=true.

data.clients[n].
interactionsChain[n].
keyword 		string

Ключевая фраза.

Отдаётся только если withInteractionChainSources=true.

data.clients[n].
ctCookies 		array Массив основных кук клиента.
data.clients[n].
ctCookiesDuplicates 		array

Массив кук клиента, которые не учитываются при построении цепочки взаимодействий.

Отдаётся только если withCtCookiesDuplicates=true.

data.clients[n].tags

 object

Объект с тегами.

Отдаётся только если withTags=true.

data.clients[n].tags.interactionsTags array

Массив с тегами из взаимодействий клиента.

Формат: 

"interactionsTags": [
   {"type": "AUTO-PN", "name": "Целевой"},
   {"type": "AUTO-TG", "name": "Тест"}
]

в котором:

  • type — тип тега;
  • name — название тега.
data.clients[n].tags.clientTags array

Массив с тегами из клиента.

Формат: 

"clientTags": [
   {"type": "MANUAL", "name": "Тест"}
]

в котором:

  • type — тип тега;
  • name — название тега.
data.clients[n].managers

 object

Объект с менеджерами.

Отдаётся только если withManagers=true.

data.clients[n].managers.interactionsManagers

array Массив с менеджерами из взаимодействий клиента.
data.clients[n].managers.clientManagers array Массив с менеджерами клиента.
data.clients[n].customFields object

Объект с пользовательскими полями.

Отдаётся только если withCustomFields=true.

data.clients[n].customFields.interactionsCustomFields array

Массив с пользовательскими полями из взаимодействий клиента.

Формат: 

"interactionsCustomFields": [
   {"field": "model", "value": "Калина"},
   {"field": "brand", "value": "Лада"}
]

в котором:

  • field — название поля в API
  • value — значение поля
data.clients[n].customFields.clientCustomFields array

Массив с пользовательскими полями клиента.

Формат: 

"clientCustomFields": [
   {"field": "rating", "value": 8},
   {"field": "birthday", "value": "01-01-1990"}
]

в котором:

  • field — название поля в API;
  • value — значение поля.
data.clients[n].interactions object

Объект с информацией о типах взаимодействий клиента и их количестве.

Формат: 

"interactions": {
   "call": 1,
   "chat": 3,
   "goal": 5,
   "request": 4,
   "scenario": 14,
   "session": 9,
   "order": 9,
   "ecommerce": 1
}

Названия типов взаимодействий — такие же как и в data.clients[n].interactionsChain[n].type


data.clients[n].ltv number Выручка (LTV) клиента.
data.clients[n].ltvCurrencyCode string Валюта выручки (LTV) клиента.
data.clients[n].imports array

Массив импортированных данных по клиентам.

Отдаётся только если в запросе указан параметр withImports=true и у клиента есть импортированные данные. Иначе отдаётся null.

data.clients[n].imports[m].importLogId integer ID операции импорта данных по клиентам в Calltouch.
data.clients[n].imports[m].externalClientId string

ID клиента из внешней системы, из импорта данных.

data.clients[n].clientContacts object Объект с контактами клиента из импорта.
data.clients[n].clientContacts.
mainContacts 		object Основные контакты клиента из импорта.
data.clients[n].clientContacts.
mainContacts.fio 		string

Основное ФИО клиента из импорта.

data.clients[n].imports[m].clientContacts.
mainContacts.phoneNumber 		string

Основной номер телефона клиента из импорта.

data.clients[n].imports[m].clientContacts.
mainContacts.email 		string

Основной email клиента из импорта.

data.clients[n].imports[m].clientContacts.
mainContacts.vkId 		string

Основной ID ВКонтакте клиента из импорта.

data.clients[n].imports[m].clientContacts.
mainContacts.tgId 		string

Основной ID Telegram клиента из импорта.

data.clients[n].imports[m].clientContacts.
mainContacts.tgUsername 		string

Основной Telegram Username клиента из импорта.

data.clients[n].imports[m].clientContacts.
mainContacts.waPhoneNumber 		string

Основной номер телефона клиента в Whatsapp из импорта.

data.clients[n].imports[m].clientContacts.
otherContacts 		object Дополнительные контакты клиента из импорта.
data.clients[n].imports[m].clientContacts.
otherContacts.phoneNumber 		array

Дополнительные номера телефона клиента из импорта.

data.clients[n].imports[m].clientContacts.
otherContacts.email 		array

Дополнительные email клиента из импорта.

data.clients[n].imports[m].clientContacts.
data.otherContacts.vkId 		array

Дополнительные ID ВКонтакте клиента из импорта.

data.clients[n].imports[m].clientContacts.
otherContacts.tgId 		array

Дополнительные ID Telegram клиента из импорта.

data.clients[n].imports[m].clientContacts.
otherContacts.tgUsername 		array

Дополнительные Telegram Username клиента из импорта.

data.clients[n].imports[m].clientContacts.
otherContacts.waPhoneNumber 		array

Дополнительные номера телефона клиента в Whatsapp из импорта.

data.clients[n].imports[m].tags array

Массив тегов, которые были загружены в клиента при импорте.

data.clients[n].imports[m].managers array

Массив менеджеров, которые были загружены в клиента при импорте.

data.clients[n].imports[m].customFields array

Массив пользовательских полей, которые были загружены в клиента при импорте.

Формат: 

"customFields": [
   {"field": "name", "value": "Вася"},
   {"field": "birthday", "value": "01-01-1990"}
]

в котором:

  • field — название поля в API
  • value — значение поля
data.clients[n].imports[m].sessionsInfo object Объект с данными о сессиях и идентификаторах из импорта.
data.clients[n].imports[m].sessionsInfo.
sessionId 		array

Массив из ID сессий Calltouch из импорта.

data.clients[n].imports[m].sessionsInfo.
ctClientId 		array

Массив из ID кук Calltouch из импорта.

data.clients[n].imports[m].sessionsInfo.
ctGlobalId 		array

Массив из ID глобальных кук Calltouch из импорта.

data.clients[n].imports[m].sessionsInfo.
gaClientId 		array

Массив из ID Google Analytics из импорта.

data.clients[n].imports[m].sessionsInfo.
yaClientId 		array

Массив из ID Яндекс.Метрика из импорта.

data.clients[n].imports[m].comment object Объект комментария из импорта.
data.clients[n].imports[m].comment.text string Комментарий к клиенту из импорта.

Типовые ошибки

При обнаружении ошибок валидации (код 400) импорт не выполняется. API возвращает описание проблемы с указанием поля: 

{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "Путь к полю с ошибкой",
                    "message": "Описание ошибки"
                }
            ]
        }
    }
}

Cписок типовых ошибок авторизации и валидации вы можете посмотреть в справке об ошибках API.

Система баллов API

Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное и часовое количество баллов. За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch.

Таблица стоимости методов экспорта данных по клиентам:

Метод URL Экспорт/импорт За успешный вызов За объект
API-метод экспорта данных по клиентам https://api.calltouch.ru/clients-service/v1/api/client/list  Экспорт  10      —

Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).


02 марта 2026
Не нашли решение проблемы?
Заполните форму, и мы вам поможем.
Похожие статьи
Недавно просмoтренные