Пошук контактів

Знайдіть контакти за значеннями їх атрибутів
Написано Микола
Оновлено 1 місяць тому

Ви можете використовувати цей метод для пошуку контактів по їх атрибутам.


➡️ Запит

URL https://api.helpcrunch.com/v1/customers/search
Метод POST
Headers Authorization: Bearer <your_api_key>

Фільтри пошуку слід розмістити в тілі вашого запиту POST. Перегляньте кілька прикладів нижче.

Приклад: Пошук за допомогою одного фільтра

{
	"filter": [
        {
            "field": "customers.email",
			"operator": "~",
			"value": "gmail"
        }
	],
	"limit": 5,
	"offset": 0,
	"sort": "customers.firstSeen",
	"order": "DESC"
}

Приклад: Пошук за допомогою кількох фільтрів

Якщо ви хочете отримати контакти, які відповідають усім фільтрам, використовуйте атрибут "comparison": "AND" у тілі запиту POST. Щоб отримати контакти, які відповідають будь-якому з фільтрів, використовуйте значення OR.

{
  "comparison": "AND",
  "filter": [
    {
      "field": "customers.name",
      "operator": "=",
      "value": "John"
    },
    {
      "field": "customers.id",
      "operator": ">",
      "value": 18
    },
    {
      "field": "customers.lastSeen",
      "operator": ">=",
      "value": 1603885746
    },
    {
      "field": "customers.tagsData",
      "operator": "=",
      "value": [
        {
          "name": "Lead"
        }
      ]
    }
  ],
  "sort": "customers.firstSeen",
  "order": "desc",
  "offset": 0,
  "limit": 100
}
Порада. Ви можете вказати декілька тегів у масиві customers.tagsData. Результати пошуку видадуть контакти, у яких будуть присутні всі перелічені теги (наприклад, tag1 і tag2). Якщо ви хочете шукати або за першим, або за другим тегом, вам слід додати окремі фільтри для кожного з тегів і використовувати OR в атрибуті comparison.

Можливі поля для пошуку

Значення, яке ви шукаєте, має відповідати необхідному типу, інакше запит буде невдалим. Наприклад, customers.createdAt приймає дату, тому значення не може бути рядком на кшталт «18 червня 2020».
Поле Тип Опис
customers.id Integer Унікальний ID контакту, наданий HelpCrunch
customers.name String Ім'я контакту
customers.email String Електронна адреса контакту
customers.company String Компанія контакту
customers.phone String Номер телефону контакту
customers.countryCode String Код країни контакту
customers.city String Місто контакту
customers.regionCode String Код регіону контакту
customers.tagsData Array of Strings Теги, призначені для чату, напр. [{"name": "Lead"}, {"name": "Paid"}]
customers.lastSeen Date (UNIX timestamp) Дата та час останнього візиту контакту
customers.userId String Власний унікальний ID контакту, який ви можете передати в HelpCrunch за допомогою Автентифікації користувача

Можливі оператори

Оператор має бути введений у форматі String, наприклад ">". Оператор має бути сумісним із типом даних поля. Ви не можете шукати текстові значення за допомогою "<", оскільки він працює лише для цілих чисел і дат.

Оператор Дійсні типи даних поля Опис
= Всі типи даних Дорівнює
!= Усі типи даних (крім масивів) Не дорівнює
> Integer чи Date (UNIX Timestamp) Більше за
< Integer чи Date (UNIX Timestamp) Нижче за
>= Integer чи Date (UNIX Timestamp) Більше за або дорівнює
<= Integer чи Date (UNIX Timestamp) Нижче за або дорівнює
~ String Містить
!~ String Не містить

Параметри сортування

Щоб указати тип сортування, вам слід додати атрибути sort і order до тіла запиту POST.

    "sort": "customers.firstSeen",
    "order": "ASC"

Ви можете сортувати клієнтів за наступними полями:

Поле Опис
customers.firstSeen за датою першого візиту клієнтів
customers.lastSeen за датою останнього візиту клієнтів

Щоб відсортувати клієнтів у порядку спадання, використовуйте значення DESC. У порядку зростання використовуйте значення ASC.

✅ Відповідь на успішний запит

Якщо ваш запит пройшов успішно, ви отримаєте код статусу успішного виконання 200 OK разом із наведеним нижче тілом відповіді.

{
  "data": [
    {
      "id": 542335,
      "name": "John Doe",
      "email": "[email protected]",
      "userId": "user_1234567890",
      "company": "Example Inc.",
      "phone": "+10233456781",
      "firstSeen": "1603885746",
      "lastSeen": "1603885746",
      "location": {
        "regionCode": "Kyyivs'ka Oblast",
        "countryCode": "UA",
        "city": "Kyiv"
      },
      "device": {
        "id": 542335,
        "ip": "192.168.1.1",
        "timezone": "Europe/Kiev",
        "platform": "desktop",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36"
      },
      "unsubscribed": false,
      "blocked": false,
      "source": "https://example.com",
      "referer": "https://example.com",
      "lastPage": "https://example.com",
      "locale": "uk",
      "createdFrom": "telegram",
      "integrationId": "465847687",
      "notes": "Lorem ipsum",
      "tags": [
        {
          "name": "vip",
          "color": "#ff0000"
        }
      ],
      "customData": {
        "subscription_status": "active",
        "number_of_payments": 15,
        "last_paid_amount": 15.99,
        "last_payment_date": 1603885746,
        "last_invoice_url": "https://example.com/invoice.html",
        "last_payment_was_successful": true
      }
    }
  ],
  "total": 256
}

Ви можете отримати деталі по кожному полю обʼєкту контакту у статті Модель даних контакту.

Обмеження

За замовчуванням цей метод повертає лише перших 100 клієнтів. Щоб отримати інший список клієнтів, вам слід використовувати параметри offset і limit у тілі запиту POST.

    "limit": 50,
    "offset": 100,

Загальний ліміт запитів становить 120 за хвилину.

🛑 Відповіді з помилками

Ви можете отримати один із наведених нижче кодів статусу помилки та відповіді. Детальніше про коди помилок ви можете прочитати за посиланням.

400 Bad Request

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "customer",
      "message": "This value should be of type numeric."
    },
    {
      "code": "filter[0].field",
      "message": "This value should not be blank."
    }
  ]
}

401 Unauthorized

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "unauthorized",
      "message": "Unauthorized"
    }
  ]
}

429 Too Many Requests

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "too_many_requests",
      "message": "Too many requests"
    }
  ]
}
Чи була наша стаття корисною?