Ви можете шукати серед кількох контактів за значеннями їх атрибутів, щоб знайти саме тих, хто вам потрібен.
➡️ Запит
| 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": "OR",
"filter": [
{
"field": "customers.email",
"operator": "~",
"value": "gmail"
},
{
"field": "customers.tagsData",
"operator": "=",
"value": [{"name": "Paid"}]
}
],
"limit": 10,
"offset": 0,
"sort": "customers.lastSeen",
"order": "ASC"
}Порада. Ви можете вказати кількість тегів у масиві 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 за допомогою автентифікації користувача |
Прийнятні оператори
Оператор має бути введений у вигляді рядка, наприклад >.
Оператор має бути сумісним із типом даних поля.
Ви не можете шукати рядкове значення за допомогою <, оскільки він працює лише для цілих чисел і дат.
| Оператор | Дійсні типи даних поля | Опис |
| = | Всі типи даних | Дорівнює |
| != | Усі типи даних (крім масивів) | Не дорівнює |
| > | 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 разом із наведеним нижче тілом відповіді.
{
"total": 184,
"data": [
{
"id": 265555,
"name": "test",
"email": "test@test.com",
"userId": "test123abc_1",
"company": "test123abc",
"phone": null,
"firstSeen": null,
"lastSeen": 1588603952,
"location": {
"regionCode": "CA",
"countryCode": "US",
"city": "Los Angeles"
},
"device": {
"id": 28874635,
"ip": "192.168.1.1",
"timezone": "America/Los Angeles",
"platform": "desktop",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.129 Safari/537.36"
},
"unsubscribed": false,
"blocked": false,
"source": "https://helpcrunch.com/",
"referer": "https://google.com/",
"locale": "en",
"notes": null,
"lastPage": "https://helpcrunch.com/zendesk-alternative.html",
"tags": [
{
"name": "direct",
"color": "#0079bf"
}
],
"customData": {
"Currency": "USD",
"Next payment date": "2020-09-01 00:40:00",
"Billing info added": true,
"Number of payments": 35,
"Subscription status": "active"
}
},
{
"id": 265580,
"name": "Lana Del Red",
"email": "lana.red@example.com",
"userId": null,
"company": null,
"phone": null,
"firstSeen": null,
"lastSeen": null,
"location": {
"regionCode": null,
"countryCode": null,
"city": null
},
"device": null,
"unsubscribed": false,
"blocked": false,
"source": null,
"referer": null,
"locale": null,
"notes": null,
"lastPage": null,
"tags": [
{
"name": "direct",
"color": "#0079bf"
}
],
"customData": {
"Tried Something": false
}
},
{
"id": 4994,
"name": "Serge Merge",
"email": "serge.merge@example.com",
"userId": "example_261",
"company": "example",
"phone": null,
"firstSeen": null,
"lastSeen": null,
"location": {
"regionCode": null,
"countryCode": null,
"city": null
},
"device": null,
"unsubscribed": false,
"blocked": false,
"source": null,
"referer": null,
"locale": null,
"notes": null,
"lastPage": null,
"tags": [
{
"name": "Lead",
"color": "#eb5a46"
},
{
"name": "Feature Request",
"color": "#0079bf"
},
{
"name": "Paid",
"color": "#61bd4f"
}
],
"customData": {
"Plan": "Premium",
"segment": null,
"Currency": "EUR",
"Became payer at": "2020-09-13 00:00:00",
"Next payment date": "2020-10-13 00:40:00",
"Billing info added": true,
"Number of payments": 1,
"Subscription status": "suspended"
}
},
{
"id": 7831682,
"name": "Vlad Darkula",
"email": "vlad.dark@transylmania.com",
"userId": "transylmania_6996",
"company": "transylmania",
"phone": null,
"firstSeen": 1593068924,
"lastSeen": 1593093642,
"location": {
"regionCode": "40",
"countryCode": "RO",
"city": "Cluj-Napoca"
},
"device": {
"id": 28889690,
"ip": "192.168.1.2",
"timezone": "Europe/Kiev",
"platform": "desktop",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36"
},
"unsubscribed": true,
"blocked": true,
"source": "https://www.blood.co.uk/",
"referer": null,
"locale": "ro",
"notes": null,
"lastPage": "https://www.blood.co.uk/who-can-give-blood/getting-an-appointment-to-give-blood/",
"tags": [],
"customData": {
"Plan": "Enterprise (Unlimited) $9999/mo",
"segment": "PotentialChurn_premium_seg1",
"Currency": "USD",
"Emails sent": 621,
"Next payment date": "2020-09-01 00:40:00",
"Billing info added": true,
"Number of payments": 35,
"Subscription status": "active"
}
}
]
}Обмеження
За замовчуванням цей метод повертає лише перших 100 клієнтів. Щоб отримати інший список клієнтів, вам слід використовувати параметри offset і limit у тілі запиту POST.
"limit": 50,
"offset": 100,Загальний ліміт запитів становить 120 за хвилину.
🛑 Відповіді з помилками
Ви можете отримати один із наведених нижче кодів статусу помилки та відповіді.
400 Bad Request
{
"errors": [
{
"code": "validation_error",
"message": "order value is invalid"
},
{
"code": "validation_error",
"message": "sort value is invalid"
},
{
"code": "validation_error",
"message": "field value is invalid"
},
{
"code": "validation_error",
"message": "operator value is invalid"
},
{
"code": "invalid_field",
"message": "customers.id value is invalid"
},
{
"code": "validation_error",
"message": "limit value is invalid"
}
]
}401 Unauthorized
{
"errors": [
{
"code": "invalid_token",
"message": "Invalid token"
}
]
}404 Not Found
{
"errors": [
{
"code": "entity_not_found",
"message": "Customer not found"
}
]
}429 Too Many Requests
{
"errors": [
{
"code": "too_many_requests",
"message": "You have exceeded your requests limit"
}
]
}