Get users (leads)

Get leads. A visitor is considered as a “lead” if the software knows contacts: name, email, phone, User ID or there was at least one converationwith this user.

We use this method in the Leads section.




This method follows the general rules. Arguments are transmitted as GET or POST parameters.

Argument Description
auth_token Required. Authorization token (requires scope: users-list)
filters Filters. Filters format. Default: all users
sort_prop Property used for sorting lead list. Default: $last_seen (last activity)
sort_order Sorting order (asc - ascending, desc - descending). Default: desc
offset Pagination. Offset from the beginning (default: 0)
limit Pagination. The maximum number of leads that will be returned (from 0 to 50. Default: 20)


By default, all leads (without filters) are returned. To find the ones you need, use the filters field. For example, to get only leads from a given segment, those who came during current day or get leads by name, email, etc.

The data returned by this method is updated with a several minutes delay. Therefore, it may differ from the data in the lead card (if it has not updated yet).

Pagination in this method is slightly different from pagination in other methods. Instead of the usual after and count, offset and limit parameters are used. In case of receiving a large number of leads through pagination, extra may be added to the list. Therefore, it is possible that the same user will be in several consecutive requests.

For example, if offset=0, limit=20 for the first request, offset=20, limit=20 for the second request, and one new user is added between the calls at the top, then the twentieth user on the first call will be the first on the second call. You need to check the ID on your side to exclude duplicates. Another option is to use export to get a large number of users at a time (in this case we solve this problem for you).

If the returned users are less than limit, then all users are returned. For example, if you get 5 users with limit=20, this means that all users are returned.


  "meta": {
    "status": 200
  "data": {
    "total": 245,
    "users": [
        "id": 3568,
        "presence": "offline",
        "props": {
          "$event_18_first": "2014-06-15T22:14:08",
          "$event_18_last": "2014-06-23T07:50:46",
          "$event_18_count": 4,
          "$last_contacted": "2016-02-12T15:33:31",
          "$email": "",
          "$sessions": 1,
          "$last_seen": "2014-06-17T08:56:03",

The answer will contain an array with users.

The total field contains the total number of users who satisfy the specified filters.

The users field contains an array of users. The used format is slightly different from the usual User object.

Each user contains the fields: id (user id), presence (status) and props (properties).

More about user properties and user status


curl -X GET '$self_app/users?auth_token=XXX'