You can search for multiple customers by the value of their attributes in order to fetch exactly the ones you want.

➡️ Request

Search filters should be placed to the body of your POST request. Check a couple of examples below.

Read more about authorization header here.

Example: Search with a single filter

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

Example: Search with multiple filters

If you want to get customers that match all the filters, use "comparison": "AND" attribute in the body of your POST request. To fetch customers matching any of the given filters, use OR value instead.

{
  "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
}

Accepted searchable fields

Accepted operators

Sorting options

To specify the sorting type, you should add sort and order attributes to the body of your POST request.

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

You can sort customers by the following fields:

To sort customers in descending order, use DESC value. For ascending order use ASC value.

✅ Successful Response

If your request has succeeded, you'll get a 200 OK success status code together with the following response body.

{
  "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
}

You can get details on every Customer Object field in the Customer model article.

Limits

By default, this method returns only the first 100 customers. To get a different set of customers, you should use the offset and limit parameters in the body of your POST request.

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

The overall requests limit is 120 per minute

🛑 Error Responses

You may get one of the following error status codes and responses. More info on the errors is available here.

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"
    }
  ]
}

If you have any questions regarding the REST API, feel free to chat us any time. 

👩‍💻 Happy Coding! 👨‍💻