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

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

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


➡️ Запит

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"
        }
    ]
}
Чи була наша стаття корисною?