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

➡️ Запит

Фільтри пошуку слід розмістити в тілі вашого запиту 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
}

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

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

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

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

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

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

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

Щоб відсортувати клієнтів у порядку спадання, використовуйте значення 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"
    }
  ]
}